Merge pull request #159 from lsst/tickets/DM-42116

DM-42116: Validate docstrings

.github/workflows/docstyle.yaml

@@ -11,3 +11,20 @@ jobs:
     uses: lsst/rubin_workflows/.github/workflows/docstyle.yaml@main
     with:
       args: "python/lsst/ctrl/bps"
+  numpydoc:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+
+      - name: Install numpydoc
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install numpydoc
+
+      - name: Validate docstrings
+        run: |
+          python -m numpydoc.hooks.validate_docstrings $(find python -name "*.py")
+          python -m numpydoc.hooks.validate_docstrings $(find tests -name "*.py")

.pre-commit-config.yaml

@@ -9,7 +9,7 @@ repos:
       - id: trailing-whitespace
       - id: check-toml
   - repo: https://github.com/psf/black
-    rev: 23.11.0
+    rev: 23.12.0
     hooks:
       - id: black
         # It is recommended to specify the latest version of Python
@@ -18,12 +18,16 @@ repos:
         # https://pre-commit.com/#top_level-default_language_version
         language_version: python3.11
   - repo: https://github.com/pycqa/isort
-    rev: 5.12.0
+    rev: 5.13.2
     hooks:
       - id: isort
         name: isort (python)
   - repo: https://github.com/astral-sh/ruff-pre-commit
     # Ruff version.
-    rev: v0.1.6
+    rev: v0.1.8
     hooks:
       - id: ruff
+  - repo: https://github.com/numpy/numpydoc
+    rev: "v1.6.0"
+    hooks:
+      - id: numpydoc-validation

pyproject.toml

@@ -159,3 +159,22 @@ max-doc-length = 79
 
 [tool.ruff.pydocstyle]
 convention = "numpy"
+
+[tool.numpydoc_validation]
+checks = [
+    "all",  # All except the rules listed below.
+    "SA01",  # See Also section.
+    "EX01",  # Example section.
+    "SS06",  # Summary can go into second line.
+    "GL01",  # Summary text can start on same line as """
+    "GL08",  # Do not require docstring.
+    "ES01",  # No extended summary required.
+    "RT01",  # Unfortunately our @property trigger this.
+    "RT02",  # Does not want named return value. DM style says we do.
+    "SS05",  # pydocstyle is better at finding infinitive verb.
+]
+exclude = [
+    '^__init__$',
+    '^commands\.',  # Click docstrings, not numpydoc
+    '\._[a-zA-Z_]+$',  # Private methods.
+]

python/lsst/ctrl/bps/bps_draw.py

@@ -42,7 +42,7 @@ def draw_networkx_dot(graph, outname):
     graph : `networkx.DiGraph`
         The graph which graphical representation should be persisted.
     outname : `str`
-        Output filename for drawn graph
+        Output filename for drawn graph.
     """
     # Note:  Leaving function here for now.  Want to move
     #        more of the drawing attributes, etc here in

python/lsst/ctrl/bps/bps_reports.py

@@ -285,7 +285,7 @@ def compile_job_summary(jobs):
     Parameters
     ----------
     jobs : `list` [`lsst.ctrl.bps.WmsRunReport`]
-        List of
+        List of run reports.
 
     Returns
     -------

python/lsst/ctrl/bps/cli/bps.py

@@ -62,7 +62,7 @@ class BpsCli(LoaderCLI):
 @log_file_option()
 @log_tty_option()
 @log_label_option()
-def cli(log_level, long_log, log_file, log_tty, log_label):
+def cli(log_level, long_log, log_file, log_tty, log_label):  # numpydoc ignore=PR01
     """Command line interface for BPS."""
     pass
 

python/lsst/ctrl/bps/cli/opt/option_groups.py

@@ -24,7 +24,7 @@
 #
 # You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
-"""Option groups for bps
+"""Option groups for bps.
 """
 
 __all__ = ["submission_options"]

python/lsst/ctrl/bps/cli/opt/options.py

@@ -24,7 +24,7 @@
 #
 # You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
-"""bps-specific command-line options.
+"""The bps-specific command-line options.
 """
 
 __all__ = [

python/lsst/ctrl/bps/clustered_quantum_graph.py

@@ -52,18 +52,18 @@ class QuantaCluster:
 
     Parameters
     ----------
-    name: `str`
+    name : `str`
         Lookup key (logical file name) of file/directory. Must
         be unique within ClusteredQuantumGraph.
-    label: `str`
+    label : `str`
         Value used to group clusters.
     tags : `dict` [`str`, `Any`], optional
         Arbitrary key/value pairs for the cluster.
 
     Raises
     ------
     ValueError
-        Raised if invalid name (e.g., name contains /)
+        Raised if invalid name (e.g., name contains /).
     """
 
     def __init__(self, name, label, tags=None):
@@ -85,7 +85,6 @@ def from_quantum_node(cls, quantum_node, template):
         ----------
         quantum_node : `lsst.pipe.base.QuantumNode`
             QuantumNode for which to make into a single quantum cluster.
-
         template : `str`
             Template for creating cluster name.
 
@@ -136,6 +135,7 @@ def add_quantum_node(self, quantum_node):
         Parameters
         ----------
         quantum_node : `lsst.pipe.base.QuantumNode`
+            Quantum node to add.
         """
         _LOG.debug("quantum_node = %s", quantum_node)
         _LOG.debug("quantum_node.nodeId = %s", quantum_node.nodeId)
@@ -248,7 +248,7 @@ def add_cluster(self, clusters_for_adding):
 
         Parameters
         ----------
-        clusters_for_adding: `QuantaCluster` or `Iterable` [`QuantaCluster`]
+        clusters_for_adding : `QuantaCluster` or `Iterable` [`QuantaCluster`]
             The cluster to be added to the ClusteredQuantumGraph.
         """
         for cluster in ensure_iterable(clusters_for_adding):
@@ -420,7 +420,6 @@ def save(self, filename, format_=None):
         ----------
         filename : `str`
             File to which the ClusteredQuantumGraph should be serialized.
-
         format_ : `str`, optional
             Format in which to write the data. It defaults to pickle format.
         """
@@ -457,7 +456,6 @@ def draw(self, filename, format_=None):
         ----------
         filename : `str`
             File to which the ClusteredQuantumGraph should be serialized.
-
         format_ : `str`, optional
             Format in which to draw the data. It defaults to dot format.
         """

python/lsst/ctrl/bps/constants.py

@@ -25,7 +25,7 @@
 # You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <https://www.gnu.org/licenses/>.
 
-"""Symbolic constants
+"""Symbolic constants.
 """
 
 from astropy import units as u

python/lsst/ctrl/bps/drivers.py

@@ -187,6 +187,8 @@ def acquire_qgraph_driver(config_file, **kwargs):
     ----------
     config_file : `str`
         Name of the configuration file.
+    **kwargs : `~typing.Any`
+        Additional modifiers to the configuration.
 
     Returns
     -------
@@ -252,6 +254,8 @@ def cluster_qgraph_driver(config_file, **kwargs):
     ----------
     config_file : `str`
         Name of the configuration file.
+    **kwargs : `~typing.Any`
+        Additional modifiers to the configuration.
 
     Returns
     -------
@@ -297,6 +301,8 @@ def transform_driver(config_file, **kwargs):
     ----------
     config_file : `str`
         Name of the configuration file.
+    **kwargs : `~typing.Any`
+        Additional modifiers to the configuration.
 
     Returns
     -------
@@ -347,6 +353,8 @@ def prepare_driver(config_file, **kwargs):
     ----------
     config_file : `str`
         Name of the configuration file.
+    **kwargs : `~typing.Any`
+        Additional modifiers to the configuration.
 
     Returns
     -------
@@ -388,6 +396,8 @@ def submit_driver(config_file, **kwargs):
     ----------
     config_file : `str`
         Name of the configuration file.
+    **kwargs : `~typing.Any`
+        Additional modifiers to the configuration.
     """
     kwargs.setdefault("runWmsSubmissionChecks", True)
 
@@ -471,7 +481,7 @@ def report_driver(wms_service, run_id, user, hist_days, pass_thru, is_global=Fal
     user : `str`
         A user name the report will be restricted to.
     hist_days : int
-        Number of days
+        Number of days.
     pass_thru : `str`
         A string to pass directly to the WMS service class.
     is_global : `bool`, optional