From 0cb2fa2663d311ac8b5541a8a5046f145eccb2fc Mon Sep 17 00:00:00 2001 From: Santiago Soler Date: Tue, 15 Oct 2024 13:17:40 -0700 Subject: [PATCH] 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. --- boule/_ellipsoid.py | 2 ++ boule/_sphere.py | 2 ++ doc/_templates/autosummary/class.rst | 21 +++++---------------- doc/conf.py | 13 +++++++------ env/requirements-docs.txt | 1 + environment.yml | 1 + 6 files changed, 18 insertions(+), 22 deletions(-) diff --git a/boule/_ellipsoid.py b/boule/_ellipsoid.py index e880442a..cd25aa00 100644 --- 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 index f1f2bc79..c672bd6d 100644 --- 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 index 5336c7b0..4cc3fe1f 100644 --- 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
diff --git a/doc/conf.py b/doc/conf.py index 0a66c816..7793b247 100644 --- 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 index 7da67025..50d413fe 100644 --- 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 index 72105385..3089cc26 100644 --- 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.*