diff --git a/docs/conf.py b/docs/conf.py index 13e77547b..5d0af1b40 100755 --- a/docs/conf.py +++ b/docs/conf.py @@ -15,7 +15,6 @@ import inspect import os import sys -import tomllib import warnings from pathlib import Path @@ -184,22 +183,6 @@ # ---------------- numpydoc_class_members_toctree = False # https://stackoverflow.com/a/73294408 -with open(PROJECT_ROOT / "tools/tool-data.toml", "rb") as f: - numpydoc_skip_errors = tomllib.load(f)["numpydoc_skip_errors"] - -numpydoc_validation_checks = {"all"} | set(numpydoc_skip_errors) -numpydoc_validation_exclude = { # regex to ignore during docstring check - r"\.__getitem__", - r"\.__contains__", - r"\.__hash__", - r"\.__mul__", - r"\.__sub__", - r"\.__add__", - r"\.__iter__", - r"\.__div__", - r"\.__neg__", -} - # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". diff --git a/tools/numpydoc-public-api.py b/tools/numpydoc-public-api.py index b7aef228d..70fc6d41e 100644 --- a/tools/numpydoc-public-api.py +++ b/tools/numpydoc-public-api.py @@ -11,7 +11,6 @@ import importlib import logging import sys -import tomllib import types from pathlib import Path @@ -26,6 +25,51 @@ PUBLIC_MODULES = ["parcels", "parcels.interpolators"] ROOT_PACKAGE = "parcels" +# full list of numpydoc error codes: https://numpydoc.readthedocs.io/en/latest/validation.html +SKIP_ERRORS = [ + "GL01", # parcels is fine with the summary line starting directly after `"""`, or on the next line. + "SA01", # Parcels doesn't require the "See also" section + "SA04", # + "ES01", # We don't require the extended summary for all docstrings + "EX01", # We don't require the "Examples" section for all docstrings + "SS06", # Not possible to make all summaries one line + # + # To be fixed up + "GL02", # Closin÷g quotes should be placed in the line after the last text in the docstring (do not close the quotes in the same line as the text, or leave a blank line between the last text and the quotes) + "GL03", # Double line break found; please use only one blank line to separate sections or paragraphs, and do not leave blank lines at the end of docstrings + "GL05", # Tabs found at the start of line "{line_with_tabs}", please use whitespace only + "GL06", # Found unknown section "{section}". Allowed sections are: {allowed_sections} + "GL07", # Sections are in the wrong order. Correct order is: {correct_sections} + "GL08", # The object does not have a docstring + "SS01", # No summary found (a short summary in a single line should be present at the beginning of the docstring) + "SS02", # Summary does not start with a capital letter + "SS03", # Summary does not end with a period + "SS04", # Summary contains heading whitespaces + "SS05", # Summary must start with infinitive verb, not third person (e.g. use "Generate" instead of "Generates") + "PR01", # Parameters {missing_params} not documented + "PR02", # Unknown parameters {unknown_params} + "PR03", # Wrong parameters order. Actual: {actual_params}. Documented: {documented_params} + "SA02", # Missing period at end of description for See Also "{reference_name}" reference + "SA03", # Description should be capitalized for See Also + # + # TODO consider whether to continue ignoring the following + "GL09", # Deprecation warning should precede extended summary + "GL10", # reST directives {directives} must be followed by two colons + "PR04", # Parameter "{param_name}" has no type + "PR05", # Parameter "{param_name}" type should not finish with "." + "PR06", # Parameter "{param_name}" type should use "{right_type}" instead of "{wrong_type}" + "PR07", # Parameter "{param_name}" has no description + "PR08", # Parameter "{param_name}" description should start with a capital letter + "PR09", # Parameter "{param_name}" description should finish with "." + "PR10", # Parameter "{param_name}" requires a space before the colon separating the parameter name and type + "RT01", # No Returns section found + "RT02", # The first line of the Returns section should contain only the type, unless multiple values are being returned + "RT03", # Return value has no description + "RT04", # Return value description should start with a capital letter + "RT05", # Return value description should finish with "." + "YD01", # No Yields section found +] + def is_built_in(type_or_instance: type | object): if isinstance(type_or_instance, type): @@ -100,8 +144,6 @@ def main(): logger.setLevel(log_level) - with open(PROJECT_ROOT / "tools/tool-data.toml", "rb") as f: - skip_errors = tomllib.load(f)["numpydoc_skip_errors"] public_api = [] for module in PUBLIC_MODULES: public_api += walk_module(module) @@ -117,7 +159,7 @@ def main(): if res["type"] in ("module", "float", "int", "dict"): continue for err in res["errors"]: - if err[0] not in skip_errors: + if err[0] not in SKIP_ERRORS: print(f"{item}: {err}") errors += 1 sys.exit(errors) diff --git a/tools/tool-data.toml b/tools/tool-data.toml deleted file mode 100644 index b0345d144..000000000 --- a/tools/tool-data.toml +++ /dev/null @@ -1,46 +0,0 @@ -# full list of numpydoc error codes: https://numpydoc.readthedocs.io/en/latest/validation.html -numpydoc_skip_errors = [ - "SA01", # Parcels doesn't require the "See also" section - "SA04", # - "ES01", # We don't require the extended summary for all docstrings - "EX01", # We don't require the "Examples" section for all docstrings - "SS06", # Not possible to make all summaries one line - - # To be fixed up - "GL03", # Double line break found; please use only one blank line to separate sections or paragraphs, and do not leave blank lines at the end of docstrings - "GL05", # Tabs found at the start of line "{line_with_tabs}", please use whitespace only - "GL06", # Found unknown section "{section}". Allowed sections are: {allowed_sections} - "GL07", # Sections are in the wrong order. Correct order is: {correct_sections} - "GL08", # The object does not have a docstring - "SS01", # No summary found (a short summary in a single line should be present at the beginning of the docstring) - "SS02", # Summary does not start with a capital letter - "SS03", # Summary does not end with a period - "SS04", # Summary contains heading whitespaces - "SS05", # Summary must start with infinitive verb, not third person (e.g. use "Generate" instead of "Generates") - "PR01", # Parameters {missing_params} not documented - "PR02", # Unknown parameters {unknown_params} - "PR03", # Wrong parameters order. Actual: {actual_params}. Documented: {documented_params} - "SA02", # Missing period at end of description for See Also "{reference_name}" reference - "SA03", # Description should be capitalized for See Also - - #? Might conflict with Ruff rules. Needs more testing... Enable ignore if they conflict - # "GL01", # Docstring text (summary) should start in the line immediately after the opening quotes (not in the same line, or leaving a blank line in between) - # "GL02", # Closing quotes should be placed in the line after the last text in the docstring (do not close the quotes in the same line as the text, or leave a blank line between the last text and the quotes) - - # TODO consider whether to continue ignoring the following - "GL09", # Deprecation warning should precede extended summary - "GL10", # reST directives {directives} must be followed by two colons - "PR04", # Parameter "{param_name}" has no type - "PR05", # Parameter "{param_name}" type should not finish with "." - "PR06", # Parameter "{param_name}" type should use "{right_type}" instead of "{wrong_type}" - "PR07", # Parameter "{param_name}" has no description - "PR08", # Parameter "{param_name}" description should start with a capital letter - "PR09", # Parameter "{param_name}" description should finish with "." - "PR10", # Parameter "{param_name}" requires a space before the colon separating the parameter name and type - "RT01", # No Returns section found - "RT02", # The first line of the Returns section should contain only the type, unless multiple values are being returned - "RT03", # Return value has no description - "RT04", # Return value description should start with a capital letter - "RT05", # Return value description should finish with "." - "YD01", # No Yields section found -]