maint: enabling docstring checks

.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
+          - LICENSE

doc/changelog.d/1342.documentation.md

@@ -0,0 +1 @@
+Maint: enabling docstring checks

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"]

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/.*',
+]