Replace Sphinx napoleon for numpydoc

Replace the builtin Sphinx plugin `napoleon` for `numpydoc`. This solves
the issue of attributes with trailing underscore not rendering properly
in docs. Add `numpydoc` as requirement for building the docs and add it
to the Sphinx configuration file. Remove `napoleon` from Sphinx
configuration. Remove the "Methods Summary" section in the Sphinx class
template since `numpydoc` builds its own list of all methods.

Related to fatiando/community#149

doc/_templates/autosummary/class.rst

@@ -4,20 +4,6 @@
 
 .. 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 %}
-
 ----
 
 {% for item in methods %}

doc/conf.py

@@ -25,13 +25,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",
@@ -57,11 +57,9 @@
 # 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
 
 # Always show the source code that generates a plot
 plot_include_source = True

env/requirements-docs.txt

@@ -1,4 +1,5 @@
 sphinx==7.2.*
+numpydoc==1.7.*
 sphinx-book-theme==1.1.*
 sphinx-gallery==0.15.*
 sphinx-copybutton==0.5.*

environment.yml

@@ -28,6 +28,7 @@ dependencies:
     - coverage
     # Documentation
     - sphinx==7.2.*
+    - numpydoc==1.7.*
     - sphinx-book-theme==1.1.*
     - sphinx-gallery==0.15.*
     - sphinx-copybutton==0.5.*