Ignore some errors at module level (#593)

Author: lucascolley

.gitignore

@@ -16,3 +16,4 @@ doc/_build
 numpydoc/tests/tinybuild/_build
 numpydoc/tests/tinybuild/generated
 MANIFEST
+node_modules

numpydoc/__main__.py

@@ -1,6 +1,6 @@
 """
-Implementing `python -m numpydoc` functionality.
-"""
+Implementing `python -m numpydoc` functionality
+"""  # '.' omitted at end of docstring for testing purposes!
 
 from .cli import main
 

numpydoc/hooks/validate_docstrings.py

@@ -60,6 +60,10 @@ def name(self) -> str:
     def is_function_or_method(self) -> bool:
         return isinstance(self.node, (ast.FunctionDef, ast.AsyncFunctionDef))
 
+    @property
+    def is_mod(self) -> bool:
+        return self.is_module
+
     @property
     def is_generator_function(self) -> bool:
         if not self.is_function_or_method:

numpydoc/tests/hooks/test_validate_hook.py

@@ -29,8 +29,6 @@ def test_validate_hook(example_module, config, capsys):
         +-------------------------------------------+-------------------------------------+---------+----------------------------------------------------+
         | file                                      | item                                | check   | description                                        |
         +===========================================+=====================================+=========+====================================================+
-        | numpydoc/tests/hooks/example_module.py:1  | example_module                      | EX01    | No examples section found                          |
-        +-------------------------------------------+-------------------------------------+---------+----------------------------------------------------+
         | numpydoc/tests/hooks/example_module.py:4  | example_module.some_function        | ES01    | No extended summary found                          |
         +-------------------------------------------+-------------------------------------+---------+----------------------------------------------------+
         | numpydoc/tests/hooks/example_module.py:4  | example_module.some_function        | PR01    | Parameters {'name'} not documented                 |

numpydoc/tests/test_main.py

@@ -117,7 +117,7 @@ def test_validate_perfect_docstring():
     assert exit_status == 0
 
 
-@pytest.mark.parametrize("args", [[], ["--ignore", "ES01", "SA01", "EX01"]])
+@pytest.mark.parametrize("args", [[], ["--ignore", "SS03"]])
 def test_lint(capsys, args):
     argv = ["lint", "numpydoc/__main__.py"] + args
     if args:
@@ -126,15 +126,11 @@ def test_lint(capsys, args):
     else:
         expected = inspect.cleandoc(
             """
-            +------------------------+----------+---------+----------------------------+
-            | file                   | item     | check   | description                |
-            +========================+==========+=========+============================+
-            | numpydoc/__main__.py:1 | __main__ | ES01    | No extended summary found  |
-            +------------------------+----------+---------+----------------------------+
-            | numpydoc/__main__.py:1 | __main__ | SA01    | See Also section not found |
-            +------------------------+----------+---------+----------------------------+
-            | numpydoc/__main__.py:1 | __main__ | EX01    | No examples section found  |
-            +------------------------+----------+---------+----------------------------+
+            +------------------------+----------+---------+------------------------------------+
+            | file                   | item     | check   | description                        |
+            +========================+==========+=========+====================================+
+            | numpydoc/__main__.py:1 | __main__ | SS03    | Summary does not end with a period |
+            +------------------------+----------+---------+------------------------------------+
         """
         )
         expected_status = 1

numpydoc/validate.py

@@ -277,6 +277,10 @@ def type(self):
     def is_function_or_method(self):
         return inspect.isfunction(self.obj)
 
+    @property
+    def is_mod(self):
+        return inspect.ismodule(self.obj)
+
     @property
     def is_generator_function(self):
         return inspect.isgeneratorfunction(_unwrap(self.obj))
@@ -690,7 +694,7 @@ def validate(obj_name, validator_cls=None, **validator_kwargs):
         if doc.num_summary_lines > 1:
             errs.append(error("SS06"))
 
-    if not doc.extended_summary:
+    if not doc.is_mod and not doc.extended_summary:
         errs.append(("ES01", "No extended summary found"))
 
     # PR01: Parameters not documented
@@ -742,20 +746,21 @@ def validate(obj_name, validator_cls=None, **validator_kwargs):
         if not doc.yields and doc.is_generator_function:
             errs.append(error("YD01"))
 
-    if not doc.see_also:
-        errs.append(error("SA01"))
-    else:
-        for rel_name, rel_desc in doc.see_also.items():
-            if rel_desc:
-                if not rel_desc.endswith("."):
-                    errs.append(error("SA02", reference_name=rel_name))
-                if rel_desc[0].isalpha() and not rel_desc[0].isupper():
-                    errs.append(error("SA03", reference_name=rel_name))
-            else:
-                errs.append(error("SA04", reference_name=rel_name))
+    if not doc.is_mod:
+        if not doc.see_also:
+            errs.append(error("SA01"))
+        else:
+            for rel_name, rel_desc in doc.see_also.items():
+                if rel_desc:
+                    if not rel_desc.endswith("."):
+                        errs.append(error("SA02", reference_name=rel_name))
+                    if rel_desc[0].isalpha() and not rel_desc[0].isupper():
+                        errs.append(error("SA03", reference_name=rel_name))
+                else:
+                    errs.append(error("SA04", reference_name=rel_name))
 
-    if not doc.examples:
-        errs.append(error("EX01"))
+        if not doc.examples:
+            errs.append(error("EX01"))
 
     errs = [err for err in errs if err[0] not in ignore_validation_comments]