Replace sphinx napoleon for numpydoc (#195)

Add `numpydoc` to requirements for building the docs. Add `numpydoc` to Sphinx configuration file. Update Sphinx template for classes. Move admonitions in `Ellipsoid` and `Sphere` classes to the Notes section so `numpydoc` can render them properly.
fatiando · Oct 15, 2024 · 0cb2fa2 · 0cb2fa2
1 parent 2a60a68
commit 0cb2fa2
Show file tree

Hide file tree

Showing 6 changed files with 18 additions and 22 deletions.
diff --git a/boule/_ellipsoid.py b/boule/_ellipsoid.py
@@ -63,6 +63,8 @@ class Ellipsoid:
     comments : str or None
         Additional comments regarding the ellipsoid (optional).
 
+    Notes
+    -----
 
     .. caution::
 

diff --git a/boule/_sphere.py b/boule/_sphere.py
@@ -60,6 +60,8 @@ class Sphere:
     comments : str or None
         Additional comments regarding the ellipsoid (optional).
 
+    Notes
+    -----
 
     .. caution::
 

diff --git a/doc/_templates/autosummary/class.rst b/doc/_templates/autosummary/class.rst
@@ -10,36 +10,25 @@ Attributes
 ----------
 
 {% for item in attributes %}
-
 .. autoattribute:: {{ objname }}.{{ item }}
-
 {% endfor %}
 
 {% endif %}
 
-Methods
--------
-
-.. rubric:: List of methods
 
-.. autosummary::
-    {% for item in methods %}
-    {% if item != "__init__" %}
-        {{ objname }}.{{ item }}
-    {% endif %}
-    {% endfor %}
+{% if methods %}
 
-.. rubric:: Methods documentation
+Methods
+-------
 
 {% for item in methods %}
 {% if item != '__init__' %}
 .. automethod:: {{ objname }}.{{ item }}
-
-----
-
 {% endif %}
 {% endfor %}
 
+{% endif %}
+
 .. raw:: html
 
      <div style='clear:both'></div>

diff --git a/doc/conf.py b/doc/conf.py
@@ -22,13 +22,13 @@
 extensions = [
     "sphinx.ext.autodoc",
     "sphinx.ext.autosummary",
+    "numpydoc",
     "sphinx.ext.coverage",
     "sphinx.ext.mathjax",
     "sphinx.ext.doctest",
     "sphinx.ext.viewcode",
     "sphinx.ext.extlinks",
     "sphinx.ext.intersphinx",
-    "sphinx.ext.napoleon",
     "sphinx_design",
     "sphinx_copybutton",
     "jupyter_sphinx",
@@ -48,11 +48,12 @@
 # Autosummary pages will be generated by sphinx-autogen instead of sphinx-build
 autosummary_generate = []
 
-# Otherwise, the Return parameter list looks different from the Parameters list
-napoleon_use_rtype = False
-# Otherwise, the Attributes parameter list looks different from the Parameters
-# list
-napoleon_use_ivar = True
+# Create cross-references for the parameter types in the Parameters, Other
+# Parameters, Returns and Yields sections of the docstring
+numpydoc_xref_param_type = True
+
+# Format the Attributes like the Parameters section.
+numpydoc_attributes_as_param_list = True
 
 # Sphinx project configuration
 templates_path = ["_templates"]

diff --git a/env/requirements-docs.txt b/env/requirements-docs.txt
@@ -1,5 +1,6 @@
 # Requirements for building the documentation
 sphinx==7.2.*
+numpydoc==1.7.*
 sphinx-book-theme==1.1.*
 sphinx-copybutton==0.5.*
 sphinx-design==0.5.*

diff --git a/environment.yml b/environment.yml
@@ -20,6 +20,7 @@ dependencies:
   - pymap3d>=2.9
   # Documentation
   - sphinx==7.2.*
+  - numpydoc==1.7.*
   - sphinx-book-theme==1.1.*
   - sphinx-copybutton==0.5.*
   - sphinx-design==0.5.*