Merge pull request #175 from cta-observatory/add_numpydoc_validation

Add validation of the documentation in pre-commit and during building.

.pre-commit-config.yaml

@@ -15,3 +15,16 @@ repos:
     hooks:
       - id: flake8
         args: [--max-line-length=88, "--extend-ignore=E203,E712"]
+  - repo: https://github.com/numpy/numpydoc
+    rev: v1.6.0
+    hooks:
+      - id: numpydoc-validation
+        exclude : |
+            (?x)^(
+                setup.py|
+                docs/conf.py|
+                magicctapipe/conftest.py|
+                magicctapipe/version.py|
+                .*__init__.py|
+                .*/tests/.*
+            )$

docs/conf.py

@@ -32,13 +32,13 @@
     "sphinx_design",
 ]
 
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
 numpydoc_show_class_members = False
 numpydoc_class_members_toctree = False
 nbsphinx_timeout = 200  # allow max 2 minutes to build each notebook
 
-# Add any paths that contain templates here, relative to this directory.
-templates_path = ["_templates"]
-
 # These links are ignored in the checks, necessary due to broken intersphinx for
 # these
 nitpick_ignore = [
@@ -91,6 +91,29 @@
     ("py:class", "ctapipe.core.container.Container"),
 ]
 
+numpydoc_xref_param_type = True
+numpydoc_xref_ignore = {"type", "optional", "default"}
+
+# Report warnings for all validation checks except those after all
+numpydoc_validation_checks = {
+    "all",
+    "EX01",
+    "ES01",
+    "GL01",
+    "PR09",
+    "RT05",
+    "SA01",
+    "SS03",
+    "SS05",
+    "SS06",
+}
+# don't report on objects that match any of these regex
+numpydoc_validation_exclude = {
+    "magicctapipe.io.BaseEventInfoContainer",
+    "magicctapipe.io.RealEventInfoContainer",
+    "magicctapipe.io.SimEventInfoContainer",
+}
+
 # -- Project information
 
 project = setup_metadata["name"]
@@ -191,9 +214,6 @@
 
 html_theme = "pydata_sphinx_theme"
 
-numpydoc_xref_param_type = True
-numpydoc_xref_ignore = {"type", "optional", "default"}
-
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3.8", None),
     "numpy": ("https://numpy.org/doc/stable/", None),

docs/developer-guide/getting-started.rst

@@ -118,6 +118,12 @@ You then have to fix the reported issues before tying to commit again.
 Note that a common problem is code not complying with the style guide, and that whenever this was the only problem found,
 simply adding the changes resulting from the pre-commit hook to the commit will result in your changes being accepted.
 
+``pre-commit`` will run the following checks:
+
+* ``isort``, which checks the import statements
+* ``black`` and ``flake8``, which check for the formatting of the code
+* ``numpydoc-validation``, which checks for the ``numpydoc`` validation tools.
+
 Run the tests to make sure everything is OK:
 
 .. code-block:: console

magicctapipe/image/calib.py

@@ -1,3 +1,6 @@
+"""
+Module for calibration
+"""
 import numpy as np
 from ctapipe.image import apply_time_delta_cleaning, number_of_islands, tailcuts_clean
 from ctapipe.instrument import CameraGeometry
@@ -35,7 +38,7 @@ def calibrate(
     config : dict
         Parameters for image extraction and calibration
     calibrator : ctapipe.calib.CameraCalibrator
-        ctapipe object needed to calibrate the camera
+        `ctapipe` object needed to calibrate the camera
     is_lst : bool
         Whether the telescope is a LST
     obs_id : int, optional
@@ -52,7 +55,6 @@ def calibrate(
         Mask of the pixels selected by the cleaning,
         array of number of p.e. in the camera pixels,
         array of the signal peak time in the camera pixels
-
     """
     if (not is_lst) and (magic_clean is None):
         raise ValueError(