Add target to validate docstrings with numpydoc

.github/workflows/style.yml

@@ -61,3 +61,6 @@ jobs:
 
       - name: Check code style
         run: make check-style
+
+      - name: Check docstrings
+        run: make check-docstrings

Makefile

@@ -35,7 +35,7 @@ format:
 	ruff format $(CHECK_STYLE)
 	burocrata --extension=py $(CHECK_STYLE)
 
-check: check-format check-style check-actions
+check: check-format check-style check-actions check-docstrings
 
 check-format:
 	ruff format --check $(CHECK_STYLE)
@@ -47,6 +47,9 @@ check-style:
 check-actions:
 	zizmor $(GITHUB_ACTIONS)
 
+check-docstrings:
+	numpydoc lint $(wildcard ${PROJECT}/**/*.py)
+
 clean:
 	find . -name "*.pyc" -exec rm -v "{}" \;
 	find . -name "*.orig" -exec rm -v "{}" \;

env/requirements-docs.txt

@@ -1,6 +1,6 @@
 # Requirements for building the documentation
 sphinx==7.2.*
-numpydoc==1.7.*
+numpydoc==1.8.*
 sphinx-book-theme==1.1.*
 sphinx-copybutton==0.5.*
 sphinx-design==0.5.*

env/requirements-style.txt

@@ -1,3 +1,4 @@
 ruff
 burocrata
+numpydoc>=1.8.0
 zizmor

environment.yml

@@ -17,7 +17,7 @@ dependencies:
   - coverage
   # Documentation
   - sphinx==7.2.*
-  - numpydoc==1.7.*
+  - numpydoc>=1.8.0
   - sphinx-book-theme==1.1.*
   - sphinx-copybutton==0.5.*
   - sphinx-design==0.5.*

pyproject.toml

@@ -131,3 +131,20 @@ source = [
 
 [tool.coverage.report]
 show_missing = true
+
+# Validate docstrings using numpydoc
+[tool.numpydoc_validation]
+checks = [
+    "all",   # report on all checks, except the below
+    "EX01",
+    "SA01",
+    "SS03",
+    "RT02",
+    "ES01",  # no extended summary
+]
+exclude = [  # don't report on objects that match any of these regex
+    '\.undocumented_method$',
+    '\.__repr__$',
+    '_version',
+    'test_[a-z_]*', # exclude all tests
+]

src/choclo/dipole/_forward.py

@@ -4,6 +4,10 @@
 #
 # This code is part of the Fatiando a Terra project (https://www.fatiando.org)
 #
+"""
+Magnetic forward modeling functions for a dipole.
+"""
+
 import numpy as np
 from numba import jit
 

src/choclo/prism/_kernels.py

@@ -750,6 +750,18 @@ def _safe_atan2(y, x):
     of the prism. This modified function has been defined according to
     [Fukushima2020]_.
 
+    Parameters
+    ----------
+    y : float
+        Numerator for the arctan.
+    x : float
+        Denominator for the arctan.
+
+    Returns
+    -------
+    float
+        Evaluation of the :math:`\text{safe-arctan}(y / x)` to be used on kernels.
+
     Notes
     -----
 
@@ -805,11 +817,11 @@ def _safe_log(x, y, z, r):
     Returns
     -------
     float
-        Evaluation of the :math:`\ln{x + r}` to be used on kernels.
+        Evaluation of the :math:`\text{safe-ln}(x + r)` to be used on kernels.
 
     Notes
     -----
-    The :math:`\text{safe\_ln}(x, r)` function is defined as:
+    The :math:`\text{safe-ln}(x, r)` function is defined as:
 
     .. math::