diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 1d51379195..5336d70740 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -49,9 +49,15 @@ repos: additional_dependencies: [toml] exclude: "tests/|examples/|__init__.py" +- repo: https://github.com/numpy/numpydoc + rev: v1.10.0 + hooks: + - id: numpydoc-validation + exclude: ^tests/|^examples/|^src/ansys/meshing/prime/(autogen|internals|relaxed_json)/ + - repo: https://github.com/ansys/pre-commit-hooks rev: v0.2.8 hooks: - id: add-license-headers args: - - LICENSE \ No newline at end of file + - LICENSE diff --git a/doc/changelog.d/1342.documentation.md b/doc/changelog.d/1342.documentation.md new file mode 100644 index 0000000000..e0fc2d1068 --- /dev/null +++ b/doc/changelog.d/1342.documentation.md @@ -0,0 +1 @@ +Maint: enabling docstring checks diff --git a/doc/source/conf.py b/doc/source/conf.py index c4e67806e3..6e6cd76cd4 100755 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -131,10 +131,30 @@ # "SS03", # Summary does not end with a period "SS04", # Summary contains heading whitespaces # "SS05", # Summary must start with infinitive verb, not third person + "PR01", # Parameters in the signature must be documented + "RT01", # Functions that return a value need a Returns section "RT02", # The first line of the Returns section should contain only the # type, unless multiple values are being returned" } +# numpydoc validates Enum classes against Enum.__new__ (*values). Exclude hand-written +# enums here; autogen enums are covered by the autogen module pattern below. +# Tests and examples are not public API (see pydocstyle excludes) and are skipped by +# the pre-commit hook via exclude_files in pyproject.toml. +numpydoc_validation_exclude = { + r"\.ColorByType$", + r"\.DisplayMeshType$", + r"\.FaceConnectivity$", + r"\.ImportTypes$", + r"\.LabelToZoneMethod$", + r"\.Examples$", + # Remove once autogen emits numpydoc-compliant parameter lines (`name : type`). + r"ansys\.meshing\.prime\.autogen\.", + # Remove once internals docstrings document all parameters and returns. + r"ansys\.meshing\.prime\.internals\.", + r"ansys\.meshing\.prime\.relaxed_json\.", +} + # static path html_static_path = ["_static"] diff --git a/pyproject.toml b/pyproject.toml index e45d1c4ddd..f4a4bf99bd 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -161,3 +161,32 @@ directory = "changed" name = "Changed" showcontent = true +[tool.numpydoc_validation] +# Keep in sync with doc/source/conf.py. +checks = [ + "GL06", + "GL07", + "GL08", + "GL09", + "GL10", + "SS01", + "SS04", + "PR01", + "RT01", + "RT02", +] +exclude = [ + '\\.ColorByType$', + '\\.DisplayMeshType$', + '\\.FaceConnectivity$', + '\\.ImportTypes$', + '\\.LabelToZoneMethod$', + '\\.Examples$', + 'ansys\\.meshing\\.prime\\.autogen\\.', + 'ansys\\.meshing\\.prime\\.internals\\.', + 'ansys\\.meshing\\.prime\\.relaxed_json\\.', +] +exclude_files = [ + '^tests/.*', + '^examples/.*', +]