From dd998a01e81da18f807629a8e753ae7c8d6090f7 Mon Sep 17 00:00:00 2001 From: Ryan May Date: Sat, 21 Dec 2019 02:46:47 -0700 Subject: [PATCH] MNT: Fix doc build with Sphinx Instead of using the sphinx-autogen script, we can now, as of Sphinx 2.1, just set a couple variables in conf.py. This is good, because running the script seems completely broken with 2.3. --- docs/Makefile | 3 --- docs/conf.py | 6 +++++- docs/infrastructureguide.rst | 2 +- setup.cfg | 2 +- 4 files changed, 7 insertions(+), 6 deletions(-) diff --git a/docs/Makefile b/docs/Makefile index 78a03fd052e..36ea4967c61 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -4,7 +4,6 @@ # You can set these variables from the command line. SPHINXOPTS = SPHINXBUILD = sphinx-build -SPHINXAUTOGEN = sphinx-autogen SPHINXPROJ = MetPy SOURCEDIR = . BUILDDIR = build @@ -28,6 +27,4 @@ overridecheck: # Manual autogen needed so we can specify the -i option so that imported names # are included in generation %: Makefile - echo Running sphinx-autogen - @$(SPHINXAUTOGEN) -i -t $(SOURCEDIR)/_templates -o $(SOURCEDIR)/api/generated $(SOURCEDIR)/api/*.rst @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/conf.py b/docs/conf.py index fdb46ab245a..f93514a7ef4 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -25,7 +25,7 @@ # -- General configuration ------------------------------------------------ # If your documentation needs a minimal Sphinx version, state it here. -needs_sphinx = '1.8' +needs_sphinx = '2.1' # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom @@ -82,6 +82,10 @@ # The suffix of source filenames. source_suffix = ['.rst', '.md'] +# Controlling automatically generating summary tables in the docs +autosummary_generate = True +autosummary_imported_members = True + # The encoding of source files. # source_encoding = 'utf-8-sig' diff --git a/docs/infrastructureguide.rst b/docs/infrastructureguide.rst index 828c547158c..1022b765565 100644 --- a/docs/infrastructureguide.rst +++ b/docs/infrastructureguide.rst @@ -31,7 +31,7 @@ This will also create a new stable set of documentation. Documentation ------------- -MetPy's documentation is built using sphinx >= 1.8. API documentation is automatically +MetPy's documentation is built using sphinx >= 2.1. API documentation is automatically generated from docstrings, written using the `NumPy docstring standard `_. There are also example scripts in the ``examples`` directory. Using the ``sphinx-gallery`` diff --git a/setup.cfg b/setup.cfg index 1f6e5bf4cf3..556dddba763 100644 --- a/setup.cfg +++ b/setup.cfg @@ -52,7 +52,7 @@ where = src [options.extras_require] dev = ipython[all]>=3.1 -doc = sphinx>=1.8; sphinx-gallery>=0.4; doc8; m2r; netCDF4 +doc = sphinx>=2.1; sphinx-gallery>=0.4; doc8; m2r; netCDF4 examples = cartopy>=0.13.1; matplotlib>=2.2.0; pyproj>=1.9.4,!=2.0.0 test = pytest>=2.4; pytest-mpl; pytest-flake8; cartopy>=0.16.0; flake8>3.2.0; flake8-builtins!=1.4.0; flake8-comprehensions; flake8-copyright; flake8-docstrings; flake8-import-order; flake8-mutable; flake8-pep3101; flake8-print; flake8-quotes; flake8-rst-docstrings; pep8-naming; netCDF4; pyproj>=1.9.4,!=2.0.0