Refine additions to docs.

Author: stefmolin

doc/install.rst

@@ -142,8 +142,8 @@ numpydoc_validation_overrides : dict
     A dictionary mapping :ref:`validation checks <validation_checks>` to a
     container of strings using :py:mod:`re` syntax specifying patterns to
     ignore for docstring validation.
-    For example, to skip the ``SS02`` check for docstrings starting with
-    the word ``Process``::
+    For example, the following skips the ``SS02`` check for docstrings
+    starting with the word ``Process``::
 
         numpydoc_validation_overrides = {"SS02": [r'^Process ']}
 

doc/validation.rst

@@ -2,6 +2,8 @@
 Validation
 ==========
 
+.. _pre_commit_hook:
+
 Docstring Validation using Pre-Commit Hook
 ------------------------------------------
 
@@ -27,42 +29,50 @@ and ``setup.cfg`` are supported; however, if the project contains both
 you must use the ``pyproject.toml`` file. The example below configures
 the pre-commit hook as follows:
 
-* ``checks``: Run all checks except ``EX01``, ``SA01``, and ``ES01`` (using the
-  same logic as the :ref:`validation during Sphinx build
-  <_validation_during_sphinx_build>`).
-* ``exclude``: Don't report any issues on anything matching the regular
-  regular expressions ``\.undocumented_method$`` or ``\.__repr__$``.
+* ``checks``: Report findings on all checks except ``EX01``, ``SA01``, and
+  ``ES01`` (using the same logic as the :ref:`validation during Sphinx build
+  <validation_during_sphinx_build>` for ``numpydoc_validation_checks``).
+* ``exclude``: Don't report issues on objects matching any of the regular
+  regular expressions ``\.undocumented_method$`` or ``\.__repr__$``. This
+  maps to ``numpydoc_validation_exclude`` from the
+  :ref:`Sphinx build configuration <validation_during_sphinx_build>`.
 * ``override_SS05``: Allow docstrings to start with "Process ", "Assess ",
   or "Access ". To override different checks, add a field for each code in
-  the form of ``override_<code>``.
+  the form of ``override_<code>`` with a collection of regular expression(s)
+  to search for in the contents of a docstring, not the object name. This
+  maps to ``numpydoc_validation_overrides`` from the
+  :ref:`Sphinx build configuration <validation_during_sphinx_build>`.
 
 ``pyproject.toml``::
 
     [tool.numpydoc_validation]
     checks = [
-        "all",   # run all checks, except the below
+        "all",   # report on all checks, except the below
         "EX01",
         "SA01",
         "ES01",
     ]
-    exclude = [
+    exclude = [  # don't report on objects that match any of these regex
         '\.undocumented_method$',
         '\.__repr__$',
     ]
-    override_SS05 = [
-        '^Process',
-        '^Assess',
-        '^Access',
+    override_SS05 = [  # override SS05 to allow docstrings starting with these words
+        '^Process ',
+        '^Assess ',
+        '^Access ',
     ]
 
 ``setup.cfg``::
 
     [tool:numpydoc_validation]
     checks = all,EX01,SA01,ES01
     exclude = \.undocumented_method$,\.__repr__$
-    override_SS05 = ^Process,^Assess,^Access
+    override_SS05 = ^Process ,^Assess ,^Access ,
+
+In addition to the above, :ref:`inline ignore comments <inline_ignore_comments>`
+can be used to ignore findings on a case by case basis.
 
-If any issues are found when commiting, a report is printed out and the
+If any issues are found when commiting, a report is printed out, and the
 commit is halted:
 
 .. code-block:: output
@@ -80,7 +90,9 @@ commit is halted:
     | src/pkg/module.py:33 | module.MyClass.parse | RT03    | Return value has no description      |
     +----------------------+----------------------+---------+--------------------------------------+
 
-See below for a full listing of checks.
+See :ref:`below <validation_checks>` for a full listing of checks.
+
+.. _validation_via_cli:
 
 Docstring Validation using Python
 ---------------------------------
@@ -98,15 +110,15 @@ For an exhaustive validation of the formatting of the docstring, use the
 ``--validate`` parameter. This will report the errors detected, such as
 incorrect capitalization, wrong order of the sections, and many other
 issues. Note that this will honor :ref:`inline ignore comments <inline_ignore_comments>`,
-but will not look for any configuration like the pre-commit hook or Sphinx
-extension do.
+but will not look for any configuration like the :ref:`pre-commit hook <pre_commit_hook>`
+or :ref:`Sphinx extension <validation_during_sphinx_build>` do.
 
 .. _validation_during_sphinx_build:
 
 Docstring Validation during Sphinx Build
 ----------------------------------------
 
-It is also possible to run docstring validation as part of the sphinx build
+It is also possible to run docstring validation as part of the Sphinx build
 process.
 This behavior is controlled by the ``numpydoc_validation_checks`` configuration
 parameter in ``conf.py``.
@@ -116,7 +128,7 @@ following line to ``conf.py``::
 
     numpydoc_validation_checks = {"PR01"}
 
-This will cause a sphinx warning to be raised for any (non-module) docstring
+This will cause a Sphinx warning to be raised for any (non-module) docstring
 that has undocumented parameters in the signature.
 The full set of validation checks can be activated by::
 
@@ -132,6 +144,48 @@ special keyword ``"all"``::
     # Report warnings for all validation checks except GL01, GL02, and GL05
     numpydoc_validation_checks = {"all", "GL01", "GL02", "GL05"}
 
+In addition, you can exclude any findings on certain objects with
+``numpydoc_validation_exclude``, which maps to ``exclude`` in the
+:ref:`pre-commit hook setup <pre_commit_hook>`::
+
+    # don't report on objects that match any of these regex
+    numpydoc_validation_exclude = [
+        '\.undocumented_method$',
+        '\.__repr__$',
+    ]
+
+Overrides based on docstring contents are also supported, but the structure
+is slightly different than the :ref:`pre-commit hook setup <pre_commit_hook>`::
+
+    numpydoc_validation_overrides = {
+        "SS02": [  # override SS05 to allow docstrings starting with these words
+            '^Process ',
+            '^Assess ',
+            '^Access ',
+        ]
+    }
+
+.. _inline_ignore_comments:
+
+Ignoring Validation Checks with Inline Comments
+-----------------------------------------------
+
+Sometimes you only want to ignore a specific check or set of checks for a
+specific piece of code. This level of fine-tuned control is provided via
+inline comments:
+
+.. code-block:: python
+
+    class SomeClass:  # numpydoc ignore=EX01,SA01,ES01
+        """This is the docstring for SomeClass."""
+
+        def __init__(self):  # numpydoc ignore=GL08
+            pass
+
+This is supported by the :ref:`CLI <validation_via_cli>`,
+:ref:`pre-commit hook <pre_commit_hook>`, and
+:ref:`Sphinx extension <validation_during_sphinx_build>`.
+
 .. _validation_checks:
 
 Built-in Validation Checks
@@ -150,19 +204,3 @@ The full mapping of validation checks is given below.
 .. literalinclude:: ../numpydoc/validate.py
    :start-after: start-err-msg
    :end-before: end-err-msg
-
-.. _inline_ignore_comments:
-
-Ignoring Validation Checks with Inline Comments
------------------------------------------------
-
-For more fine-tuned control, you can also include inline comments
-to ignore certain checks:
-
-.. code-block:: python
-
-    class SomeClass:  # numpydoc ignore=EX01,SA01,ES01
-        """This is the docstring for SomeClass."""
-
-        def __init__(self):  # numpydoc ignore=GL08
-            pass