Skip to content
Permalink
Browse files

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.
  • Loading branch information
leouieda committed Nov 28, 2019
1 parent 343c7ad commit a93363ef4e1aa0fd2eefcecdfd55767ed3e045ef
Showing with 30 additions and 22 deletions.
  1. +12 −0 doc/_templates/autosummary/class.rst
  2. +6 −3 doc/conf.py
  3. +4 −4 environment.yml
  4. +2 −4 pygmt/base_plotting.py
  5. +2 −2 pygmt/gridding.py
  6. +2 −6 pygmt/mathops.py
  7. +2 −3 requirements-dev.txt
@@ -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>

@@ -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 = {
@@ -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
@@ -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:
@@ -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
@@ -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
@@ -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

0 comments on commit a93363e

Please sign in to comment.
You can’t perform that action at this time.