From 1d080e68426637572a076f545e215c5ed3d048de Mon Sep 17 00:00:00 2001 From: Leonardo Uieda Date: Wed, 27 Nov 2019 16:58:56 +0000 Subject: [PATCH] Use napoleon instead of numpydoc with sphinx 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. --- doc/_templates/autosummary/class.rst | 12 ++++++++++++ doc/conf.py | 9 ++++++--- environment.yml | 6 +++--- pygmt/base_plotting.py | 7 ++----- pygmt/gridding.py | 4 ++-- pygmt/mathops.py | 8 ++------ requirements-dev.txt | 5 ++--- 7 files changed, 29 insertions(+), 22 deletions(-) diff --git a/doc/_templates/autosummary/class.rst b/doc/_templates/autosummary/class.rst index 0a47561ea7c..a08a2657d08 100644 --- a/doc/_templates/autosummary/class.rst +++ b/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
+ diff --git a/doc/conf.py b/doc/conf.py index 8c8c0c8fa9b..d7a055a5e47 100644 --- a/doc/conf.py +++ b/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 = { diff --git a/environment.yml b/environment.yml index 223fba60f24..b3e2d6524d5 100644 --- a/environment.yml +++ b/environment.yml @@ -5,6 +5,7 @@ channels: dependencies: - python=3.7 - pip + - gmt=6.0.0 - numpy - pandas - xarray @@ -20,8 +21,7 @@ dependencies: - black - pylint - flake8 - - sphinx<=1.8.5 - - sphinx_rtd_theme + - sphinx=2.2.1 + - sphinx_rtd_theme=0.4.3 - sphinx-gallery - nbsphinx - - numpydoc diff --git a/pygmt/base_plotting.py b/pygmt/base_plotting.py index 90648e02d6a..7b22b9aa064 100644 --- a/pygmt/base_plotting.py +++ b/pygmt/base_plotting.py @@ -156,6 +156,8 @@ def colorbar(self, **kwargs): Full option list at :gmt-docs:`colorbar.html` + {aliases} + Parameters ---------- position (D) : str @@ -176,7 +178,6 @@ def colorbar(self, **kwargs): By 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]]]``. @@ -194,18 +195,14 @@ def colorbar(self, **kwargs): Finally, append +s to draw an 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: diff --git a/pygmt/gridding.py b/pygmt/gridding.py index ed0da5b9c38..4007a0234c9 100644 --- a/pygmt/gridding.py +++ b/pygmt/gridding.py @@ -36,6 +36,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 @@ -55,8 +57,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 diff --git a/pygmt/mathops.py b/pygmt/mathops.py index dab216a0cb0..8d55f834b2b 100644 --- a/pygmt/mathops.py +++ b/pygmt/mathops.py @@ -15,44 +15,40 @@ 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 diff --git a/requirements-dev.txt b/requirements-dev.txt index 5c9c72a185f..76352e17224 100644 --- a/requirements-dev.txt +++ b/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