diff --git a/.gitignore b/.gitignore index 26f7400b..60696edd 100644 --- a/.gitignore +++ b/.gitignore @@ -16,3 +16,4 @@ doc/_build numpydoc/tests/tinybuild/_build numpydoc/tests/tinybuild/generated MANIFEST +node_modules diff --git a/numpydoc/__main__.py b/numpydoc/__main__.py index b3b6d159..8cd0943e 100644 --- a/numpydoc/__main__.py +++ b/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 diff --git a/numpydoc/hooks/validate_docstrings.py b/numpydoc/hooks/validate_docstrings.py index 562a1f09..f5251522 100644 --- a/numpydoc/hooks/validate_docstrings.py +++ b/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: diff --git a/numpydoc/tests/hooks/test_validate_hook.py b/numpydoc/tests/hooks/test_validate_hook.py index ab71a871..18b03818 100644 --- a/numpydoc/tests/hooks/test_validate_hook.py +++ b/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 | diff --git a/numpydoc/tests/test_main.py b/numpydoc/tests/test_main.py index 12c06840..bd06be3f 100644 --- a/numpydoc/tests/test_main.py +++ b/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 diff --git a/numpydoc/validate.py b/numpydoc/validate.py index c0bbd3d4..22a24ff4 100644 --- a/numpydoc/validate.py +++ b/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)) @@ -706,7 +710,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 @@ -758,20 +762,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]