Use napoleon instead of numpydoc with sphinx (#383)

The napoleon sphinx extension renders the numpy docstrings better than
numpydoc and works with newer versions of sphinx. This way, we upgrade
to a newer sphinx which works better with the readthedocs theme. Older
sphinx is also a problem for Python 3.8 packages on conda-forge.

Author: leouieda

doc/_templates/autosummary/class.rst

@@ -4,6 +4,18 @@
 
 .. autoclass:: {{ objname }}
 
+.. rubric:: Methods Summary
+
+.. autosummary::
+    {% for item in methods %}
+    {% if item != '__init__' %}
+    {{ objname }}.{{ item }}
+    {% endif %}
+    {% endfor %}
+
+.. include:: backreferences/{{ fullname }}.examples
+
 .. raw:: html
 
      <div style='clear:both'></div>
+

doc/conf.py

@@ -20,15 +20,18 @@
     "sphinx.ext.viewcode",
     "sphinx.ext.extlinks",
     "sphinx.ext.intersphinx",
-    "numpydoc",
+    "sphinx.ext.napoleon",
     "nbsphinx",
     "sphinx_gallery.gen_gallery",
 ]
 
 # Autosummary pages will be generated by sphinx-autogen instead of sphinx-build
-autosummary_generate = False
+autosummary_generate = []
 
-numpydoc_class_members_toctree = False
+# Make the list of returns arguments and attributes render the same as the
+# parameters list
+napoleon_use_rtype = False
+napoleon_use_ivar = True
 
 # configure links to GMT docs
 extlinks = {

environment.yml

@@ -5,6 +5,7 @@ channels:
 dependencies:
     - python=3.7
     - pip
+    - gmt=6.0.0
     - numpy
     - pandas
     - xarray
@@ -18,10 +19,9 @@ dependencies:
     - pytest-mpl
     - coverage
     - black
-    - pylint
+    - pylint=2.2.2
     - flake8
-    - sphinx<=1.8.5
-    - sphinx_rtd_theme
+    - sphinx=2.2.1
+    - sphinx_rtd_theme=0.4.3
     - sphinx-gallery
     - nbsphinx
-    - numpydoc

pygmt/base_plotting.py

@@ -157,6 +157,8 @@ def colorbar(self, **kwargs):
 
         Full option list at :gmt-docs:`colorbar.html`
 
+        {aliases}
+
         Parameters
         ----------
         position (D) : str
@@ -175,7 +177,6 @@ def colorbar(self, **kwargs):
             default, the anchor point on the scale is assumed to be the bottom
             left corner (BL), but this can be changed by appending +j followed
             by a 2-char justification code justify.
-
         box (F) : bool or str
             ``[+cclearances][+gfill][+i[[gap/]pen]][+p[pen]][+r[radius]]
             [+s[[dx/dy/][shade]]]``. If set to True, draws a rectangular
@@ -192,18 +193,15 @@ def colorbar(self, **kwargs):
             offset background shaded region. Here, dx/dy indicates the shift
             relative to the foreground frame [4p/-4p] and shade sets the fill
             style to use for shading [gray50].
-
         truncate (G) : list or str
             ``zlo/zhi`` Truncate the incoming CPT so that the lowest and
             highest z-levels are to zlo and zhi. If one of these equal NaN then
             we leave that end of the CPT alone. The truncation takes place
             before the plotting.
-
         scale (W) : float
             Multiply all z-values in the CPT by the provided scale. By default
             the CPT is used as is.
 
-        {aliases}
         """
         kwargs = self._preprocess(**kwargs)
         with Session() as lib:

pygmt/gridding.py

@@ -37,6 +37,8 @@ def surface(x=None, y=None, z=None, data=None, **kwargs):
 
     Full option list at :gmt-docs:`surface.html`
 
+    {aliases}
+
     Parameters
     ----------
     x, y, z : 1d arrays
@@ -56,8 +58,6 @@ def surface(x=None, y=None, z=None, data=None, **kwargs):
         Optional. The file name for the output netcdf file with extension .nc
         to store the grid in.
 
-    {aliases}
-
     Returns
     -------
     ret: xarray.DataArray or None

pygmt/mathops.py

@@ -15,47 +15,43 @@ def makecpt(**kwargs):
 
     Full option list at :gmt-docs:`makecpt.html`
 
+    {aliases}
+
     Parameters
     ----------
     cmap (C) : str
         Selects the master color palette table (CPT) to use in the
         interpolation. Full list of built-in color palette tables can be found
         at :gmt-docs:`cookbook/cpts.html#built-in-color-palette-tables-cpt`.
-
     series (T) : list or str
         ``[min/max/inc[+b|l|n]|file|list]``. Defines the range of the new CPT
         by giving the lowest and highest z-value (and optionally an interval).
         If this is not given, the existing range in the master CPT will be used
         intact.
-
     truncate (G) : list or str
         ``zlo/zhi``. Truncate the incoming CPT so that the lowest and highest
         z-levels are to zlo and zhi. If one of these equal NaN then we leave
         that end of the CPT alone. The truncation takes place before any
         resampling. See also
         :gmt-docs:`cookbook/features.html#manipulating-cpts`.
-
     output (H) : str
         Optional. The file name with extension .cpt to store the generated CPT
         file. If not given or False (default), saves the CPT as the session
         current CPT.
-
     reverse (I) : str
         Set this to True or c [Default] to reverse the sense of color
         progression in the master CPT. Set this to z to reverse the sign of
         z-values in the color table. Note that this change of z-direction
         happens before -G and -T values are used so the latter must be
         compatible with the changed z-range. See also
         :gmt-docs:`cookbook/features.html#manipulating-cpts`.
-
     continuous (Z) : bool
         Creates a continuous CPT [Default is discontinuous, i.e., constant
         colors for each interval]. This option has no effect when no -T is
         used, or when using -Tz_min/z_max; in the first case the input CPT
         remains untouched, in the second case it is only scaled to match the
         range z_min/z_max.
 
-    {aliases}
     """
     with Session() as lib:
         if "H" not in kwargs.keys():  # if no output is set

requirements-dev.txt

@@ -9,8 +9,7 @@ coverage
 black
 pylint
 flake8
-sphinx<=1.8.5
-sphinx_rtd_theme
+sphinx=2.2.1
+sphinx_rtd_theme=0.4.3
 sphinx-gallery
 nbsphinx
-numpydoc