Merge pull request #816 from AFM-SPM/ns-rse/numpydoc-pre-commit

Merging without approval as this PR is concerned solely with docstrings and doesn't touch code and is primarily about the formatting/style of those docstrings.

.git-blame-ignore-revs

@@ -1,3 +1,30 @@
+# numpydoc validation - Linting docstrings with pre-commit numpydoc
+836e1bf5347eb7a9f97e784e783045c0287b3fe9
+2580811edefac867938ee0c4b705649a493e5d4f
+b35307bb55c703b44f6a28652e33dd64cc184e43
+af779c5a16c261716097573ba8cb8a5f882e04c0
+7f0818349e7a06d51654d0554e8ba8a879402ddb
+57a0c001d79c72fd459158fcec7acb27dfae2734
+7a265dab01aa661965adf7cb0c85605e08366ea8
+83649f8697746e5c839ee90d1dc04d3a96777657
+31b3c86f532ba6c276af393dc78c839b5007fe7b
+0af8d30ff4685ee721b25272b36b3652aeaeb18f
+e028184b234e50dd67abdf1cf81e40d90f72f4f1
+46e014b1b5b73d089068e81874b56d0141eec9a3
+db41c74333a5ee0fbb9758155770c282e01e7ecb
+acfc93c178c54fef30266a27c1b0d418d0c367c7
+0c4c4f7b7f448339f83af856c78979bb0c20554a
+f79295ed2fbf989c392caf554d82077bfea7756e
+119e3d989f84f6711c1140a7dd8617fbffaa39e1
+e18d311603fbf1e9c4251382dea6d11a91a2dc17
+165f5dc1688d590b326d5664c9211eb4d10dcb6a
+3fc2d275f2d354918d0c431a786ec6aac48843a9
+86bae88351eec40ad18163478f070b972231283b
+0fd0707948c1fbca47fc4e79b7a2c04b36da5c4f
+583e0e3b9edcd31d3f81c31313999ed2016ae091
+68a220ab800406a84f726a850cc0a2230f862eb3
+a0aef99cb350575e481d0d6e8c5c39e1f0704017
+
 # codespell
 e9f1c8fa0904d643285901110e7a026f3427dc15
 

.pre-commit-config.yaml

@@ -68,6 +68,11 @@ repos:
     hooks:
       - id: nbstripout
 
+  - repo: https://github.com/numpy/numpydoc
+    rev: v1.6.0
+    hooks:
+      - id: numpydoc-validation
+
   - repo: local
     hooks:
       - id: pylint

pyproject.toml

@@ -258,6 +258,29 @@ skip = '*.spm*,*.mplstyle'
 count = ''
 quiet-level = 3
 
+[tool.numpydoc_validation]
+checks = [
+  "all", # Perform all check except those listed below
+  "ES01",
+  "EX01",
+  "PR10", # Conflicts with black formatting
+  "SA01",
+]
+exclude = [  # don't report on objects that match any of these regex
+    "\\.undocumented_method$",
+    "\\.__repr__$",
+    "^test_",
+    "^conftest",
+    "^dnatrcing",
+    "^tracingfuncs",
+    "^conf$",
+]
+override_SS05 = [  # override SS05 to allow docstrings starting with these words
+    "^Process ",
+    "^Assess ",
+    "^Access ",
+]
+
 [project.scripts]
 topostats = "topostats.entry_point:entry_point"
 run_topostats = "topostats.entry_point:legacy_run_topostats_entry_point"

topostats/entry_point.py

@@ -1,4 +1,5 @@
-"""Entry point for all TopoStats programs.
+"""
+Entry point for all TopoStats programs.
 
 Parses command-line arguments and passes input on to the relevant functions / modules.
 """
@@ -16,7 +17,16 @@
 
 
 def create_parser() -> arg.ArgumentParser:
-    """Create a parser for reading options."""
+    """
+    Create a parser for reading options.
+
+    Creates a parser, with multiple sub-parsers for reading options to run 'topostats'.
+
+    Returns
+    -------
+    arg.ArgumentParser
+        Argument parser.
+    """
     parser = arg.ArgumentParser(
         description="Run various programs relating to AFM data. Add the name of the program you wish to run."
     )
@@ -342,7 +352,24 @@ def create_parser() -> arg.ArgumentParser:
 
 
 def entry_point(manually_provided_args=None, testing=False) -> None:
-    """Entry point for all TopoStats programs."""
+    """
+    Entry point for all TopoStats programs.
+
+    Main entry point for running 'topostats' which allows the different processing steps ('process', 'filter',
+    'create_config' etc.) to be run.
+
+    Parameters
+    ----------
+    manually_provided_args : None
+        Manually provided arguments.
+    testing : bool
+        Whether testing is being carried out.
+
+    Returns
+    -------
+    None
+        Does not return anything.
+    """
     # Parse command line options, load config (or default) and update with command line options
     parser = create_parser()
     args = parser.parse_args() if manually_provided_args is None else parser.parse_args(manually_provided_args)
@@ -362,7 +389,14 @@ def entry_point(manually_provided_args=None, testing=False) -> None:
 
 
 def create_legacy_run_topostats_parser() -> arg.ArgumentParser:
-    """Create a parser reading options for the 'run_topostats' processing entry point."""
+    """
+    Create a parser reading options for the 'run_topostats' processing entry point.
+
+    Returns
+    -------
+    arg.ArgumentParser
+        Arguments to be passed to 'run_topostats'.
+    """
     parser = arg.ArgumentParser(
         description="Process AFM images. Additional arguments over-ride those in the configuration file."
     )
@@ -456,7 +490,14 @@ def create_legacy_run_topostats_parser() -> arg.ArgumentParser:
 
 
 def create_legacy_toposum_parser() -> arg.ArgumentParser:
-    """Create a parser reading options for the legacy 'toposum' summarize entry point."""
+    """
+    Create a parser reading options for the legacy 'toposum' summarize entry point.
+
+    Returns
+    -------
+    arg.ArgumentParser
+        Arguments to be passed to 'toposum'.
+    """
     parser = arg.ArgumentParser(
         description="Summarise and plot histograms, kernel density estimates and scatter plots of TopoStats"
         "grain and DNA Tracing statistics."
@@ -496,7 +537,21 @@ def create_legacy_toposum_parser() -> arg.ArgumentParser:
 
 
 def legacy_run_topostats_entry_point(args=None, testing=False) -> None:
-    """Legacy entry point for the run_topostats processing function."""
+    """
+    Legacy entry point for the run_topostats processing function.
+
+    Parameters
+    ----------
+    args : None
+        Arguments.
+    testing : bool
+        Whether functions is being tested.
+
+    Returns
+    -------
+    None
+        Does not return anything.
+    """
     parser = create_legacy_run_topostats_parser()
     args = parser.parse_args() if args is None else parser.parse_args(args)
 
@@ -509,7 +564,21 @@ def legacy_run_topostats_entry_point(args=None, testing=False) -> None:
 
 
 def legacy_toposum_entry_point(args=None, testing=False) -> None:
-    """Legacy entry point for the toposum summarizing function."""
+    """
+    Legacy entry point for the toposum summarizing function.
+
+    Parameters
+    ----------
+    args : None
+        Arguments.
+    testing : bool
+        Whether functions is being tested.
+
+    Returns
+    -------
+    None
+        Does not return anything.
+    """
     parser = create_legacy_toposum_parser()
     args = parser.parse_args() if args is None else parser.parse_args(args)