From abcd37c77b5494c4b3a4981e449f24564ddca4da Mon Sep 17 00:00:00 2001 From: Lucas Colley Date: Sat, 14 Dec 2024 16:59:53 +0000 Subject: [PATCH 1/4] ignore some errors at module level --- numpydoc/__main__.py | 2 +- numpydoc/hooks/validate_docstrings.py | 4 +++ numpydoc/tests/hooks/test_validate_hook.py | 2 -- numpydoc/tests/test_main.py | 16 ++++------ numpydoc/validate.py | 34 +++++++++++++--------- 5 files changed, 31 insertions(+), 27 deletions(-) diff --git a/numpydoc/__main__.py b/numpydoc/__main__.py index b3b6d159..08125e0e 100644 --- a/numpydoc/__main__.py +++ b/numpydoc/__main__.py @@ -1,5 +1,5 @@ """ -Implementing `python -m numpydoc` functionality. +Implementing `python -m numpydoc` functionality """ 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 138e9d48..caa64c50 100644 --- a/numpydoc/validate.py +++ b/numpydoc/validate.py @@ -276,6 +276,10 @@ def type(self): @property 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): @@ -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,22 @@ 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] From 71855ebd5f1b5291ab3a30af120869f004d49baa Mon Sep 17 00:00:00 2001 From: Lucas Colley Date: Sat, 14 Dec 2024 17:35:45 +0000 Subject: [PATCH 2/4] appease pre-commit --- numpydoc/validate.py | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/numpydoc/validate.py b/numpydoc/validate.py index caa64c50..495d7201 100644 --- a/numpydoc/validate.py +++ b/numpydoc/validate.py @@ -276,7 +276,7 @@ def type(self): @property def is_function_or_method(self): return inspect.isfunction(self.obj) - + @property def is_mod(self): return inspect.ismodule(self.obj) @@ -747,7 +747,6 @@ def validate(obj_name, validator_cls=None, **validator_kwargs): errs.append(error("YD01")) if not doc.is_mod: - if not doc.see_also: errs.append(error("SA01")) else: From 8ea672d333b2244ad6184e66716542567ec0e23a Mon Sep 17 00:00:00 2001 From: Lucas Colley Date: Sun, 22 Dec 2024 14:11:47 +0000 Subject: [PATCH 3/4] add comment --- .../83122a60e88b30a80010bc6a424a56110b6de00e.json | 1 + numpydoc/__main__.py | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) create mode 100644 node_modules/.cache/prettier/.prettier-caches/83122a60e88b30a80010bc6a424a56110b6de00e.json diff --git a/node_modules/.cache/prettier/.prettier-caches/83122a60e88b30a80010bc6a424a56110b6de00e.json b/node_modules/.cache/prettier/.prettier-caches/83122a60e88b30a80010bc6a424a56110b6de00e.json new file mode 100644 index 00000000..8aedd862 --- /dev/null +++ b/node_modules/.cache/prettier/.prettier-caches/83122a60e88b30a80010bc6a424a56110b6de00e.json @@ -0,0 +1 @@ +{"e3829fa140b67843f9d645721a5c5e3b6cba77a5":{"files":{".github/workflows/milestone-merged-prs.yml":["SIDS092s17FWnMngvxV16c+CIKM=",true],".github/dependabot.yml":["ZRskgL5v/nFn3e/SAyP9rw75nFI=",true],".circleci/config.yml":["8vqn3bWfIc/i9gpFs1uyDynvvLQ=",true],".github/workflows/test.yml":["XjKXqyVtT9ml8ggIc7MlQ8zVoLo=",true]},"modified":1734876685939}} \ No newline at end of file diff --git a/numpydoc/__main__.py b/numpydoc/__main__.py index 08125e0e..8cd0943e 100644 --- a/numpydoc/__main__.py +++ b/numpydoc/__main__.py @@ -1,6 +1,6 @@ """ Implementing `python -m numpydoc` functionality -""" +""" # '.' omitted at end of docstring for testing purposes! from .cli import main From f89b13db8f8b95df23888de8a7daf3493bed02ae Mon Sep 17 00:00:00 2001 From: Lucas Colley Date: Sun, 22 Dec 2024 14:13:36 +0000 Subject: [PATCH 4/4] gitignore node_modules --- .gitignore | 1 + .../83122a60e88b30a80010bc6a424a56110b6de00e.json | 1 - 2 files changed, 1 insertion(+), 1 deletion(-) delete mode 100644 node_modules/.cache/prettier/.prettier-caches/83122a60e88b30a80010bc6a424a56110b6de00e.json 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/node_modules/.cache/prettier/.prettier-caches/83122a60e88b30a80010bc6a424a56110b6de00e.json b/node_modules/.cache/prettier/.prettier-caches/83122a60e88b30a80010bc6a424a56110b6de00e.json deleted file mode 100644 index 8aedd862..00000000 --- a/node_modules/.cache/prettier/.prettier-caches/83122a60e88b30a80010bc6a424a56110b6de00e.json +++ /dev/null @@ -1 +0,0 @@ -{"e3829fa140b67843f9d645721a5c5e3b6cba77a5":{"files":{".github/workflows/milestone-merged-prs.yml":["SIDS092s17FWnMngvxV16c+CIKM=",true],".github/dependabot.yml":["ZRskgL5v/nFn3e/SAyP9rw75nFI=",true],".circleci/config.yml":["8vqn3bWfIc/i9gpFs1uyDynvvLQ=",true],".github/workflows/test.yml":["XjKXqyVtT9ml8ggIc7MlQ8zVoLo=",true]},"modified":1734876685939}} \ No newline at end of file