From 45c42ed3542b85fa8027de0d516c0d681cad20b0 Mon Sep 17 00:00:00 2001
From: Santiago Soler <santisoler@fastmail.com>
Date: Fri, 31 May 2024 10:41:51 -0700
Subject: [PATCH] Replace sphinx napoleon for numpydoc (#492)

Add numpydoc to requirements for building the docs. Add numpydoc to
Sphinx configuration file. Update Sphinx template for classes.
---
 doc/_templates/autosummary/class.rst | 20 +++++---------------
 doc/conf.py                          | 13 +++++++------
 env/requirements-docs.txt            |  1 +
 environment.yml                      |  1 +
 4 files changed, 14 insertions(+), 21 deletions(-)

diff --git a/doc/_templates/autosummary/class.rst b/doc/_templates/autosummary/class.rst
index f822a5776..47cf32222 100644
--- a/doc/_templates/autosummary/class.rst
+++ b/doc/_templates/autosummary/class.rst
@@ -4,21 +4,7 @@
 
 .. autoclass:: {{ objname }}
 
-.. rubric:: Methods Summary
-
-.. autosummary::
-    {% for item in members %}
-    {% if item in ['__call__'] %}
-        {{ objname }}.{{ item }}
-    {% endif %}
-    {% endfor %}
-    {% for item in methods %}
-    {% if item != '__init__' %}
-        {{ objname }}.{{ item }}
-    {% endif %}
-    {% endfor %}
-
-----
+{% if methods %}
 
 {% for item in methods %}
 {% if item != '__init__' %}
@@ -26,6 +12,10 @@
 {% endif %}
 {% endfor %}
 
+{% endif %}
+
+----
+
 .. include:: backreferences/{{ fullname }}.examples
 
 .. raw:: html
diff --git a/doc/conf.py b/doc/conf.py
index da892fbdc..fbde10d39 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -26,13 +26,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_gallery.gen_gallery",
     "sphinx_design",
     "sphinx_copybutton",
@@ -67,11 +67,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
+# Returns and Yields sections of the docstring
+numpydoc_xref_param_type = True
+
+# Format the Attributes section like the Parameters section.
+numpydoc_attributes_as_param_list = True
 
 # Always show the source code that generates a plot
 plot_include_source = True
diff --git a/env/requirements-docs.txt b/env/requirements-docs.txt
index 997bf1154..74488950c 100644
--- a/env/requirements-docs.txt
+++ b/env/requirements-docs.txt
@@ -1,5 +1,6 @@
 # Documentation building requirements
 sphinx==7.2.*
+numpydoc==1.7.*
 sphinx-book-theme==1.1.*
 sphinx-gallery==0.15.*
 sphinx-design==0.5.*
diff --git a/environment.yml b/environment.yml
index 24ca5c0af..9cfcbcd3e 100644
--- a/environment.yml
+++ b/environment.yml
@@ -28,6 +28,7 @@ dependencies:
   - boule
   # Documentation requirements
   - sphinx==7.2.*
+  - numpydoc==1.7.*
   - sphinx-book-theme==1.1.*
   - sphinx-gallery==0.15.*
   - sphinx-design==0.5.*