diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/Makefile | 4 | ||||
| -rw-r--r-- | doc/source/conf.py | 25 | ||||
| -rw-r--r-- | doc/sphinxext/autosummary.py | 11 |
3 files changed, 27 insertions, 13 deletions
diff --git a/doc/Makefile b/doc/Makefile index 47ee1fb01..d0012fff2 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -9,6 +9,8 @@ SPHINXOPTS = SPHINXBUILD = LANG=C sphinx-build PAPER = +NEED_AUTOSUMMARY = $(shell $(PYTHON) -c 'import sphinx; print sphinx.__version__ >= "0.7" and "1" or ""') + # Internal variables. PAPEROPT_a4 = -D latex_paper_size=a4 PAPEROPT_letter = -D latex_paper_size=letter @@ -95,9 +97,11 @@ dist-build: generate: build/generate-stamp build/generate-stamp: $(wildcard source/reference/*.rst) mkdir -p build +ifeq ($(NEED_AUTOSUMMARY),1) $(PYTHON) \ ./sphinxext/autosummary_generate.py source/reference/*.rst \ -p dump.xml -o source/reference/generated +endif touch build/generate-stamp html: generate diff --git a/doc/source/conf.py b/doc/source/conf.py index 6261bd8bb..d5ab2cd78 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -2,26 +2,28 @@ import sys, os, re -# If your extensions are in another directory, add it here. If the directory -# is relative to the documentation root, use os.path.abspath to make it -# absolute, like shown here. -sys.path.append(os.path.abspath('../sphinxext')) - # Check Sphinx version import sphinx if sphinx.__version__ < "0.5": raise RuntimeError("Sphinx 0.5.dev or newer required") - # ----------------------------------------------------------------------------- # General configuration # ----------------------------------------------------------------------------- # Add any Sphinx extension module names here, as strings. They can be extensions # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. + +sys.path.append(os.path.abspath('../sphinxext')) + extensions = ['sphinx.ext.autodoc', 'sphinx.ext.pngmath', 'numpydoc', - 'phantom_import', 'autosummary', 'sphinx.ext.intersphinx', - 'sphinx.ext.coverage', 'only_directives'] + 'sphinx.ext.intersphinx', 'sphinx.ext.coverage', + 'only_directives'] + +if sphinx.__version__ >= "0.7": + extensions.append('sphinx.ext.autosummary') +else: + extensions.append('autosummary') # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] @@ -211,6 +213,13 @@ intersphinx_mapping = {'http://docs.python.org/dev': None} phantom_import_file = 'dump.xml' # ----------------------------------------------------------------------------- +# Autosummary +# ----------------------------------------------------------------------------- + +import glob +autosummary_generate = glob.glob("reference/*.rst") + +# ----------------------------------------------------------------------------- # Coverage checker # ----------------------------------------------------------------------------- coverage_ignore_modules = r""" diff --git a/doc/sphinxext/autosummary.py b/doc/sphinxext/autosummary.py index 4e64a8d05..2f8a00a30 100644 --- a/doc/sphinxext/autosummary.py +++ b/doc/sphinxext/autosummary.py @@ -62,11 +62,12 @@ from sphinx.util import patfilter from docscrape_sphinx import get_doc_object import warnings -warnings.warn("The numpydoc.autosummary extension will be eventually moved to " - "sphinx.ext.autosummary. One version is already available in " - "Sphinx >= 0.6; expect this module to be deprecated after all " - "remaining features have been integrated there.", - FutureWarning, stacklevel=2) +warnings.warn( + "The numpydoc.autosummary extension can also be found as " + "sphinx.ext.autosummary in Sphinx >= 0.6, and the version in " + "Sphinx >= 0.7 is superior to the one in numpydoc. This numpydoc " + "version of autosummary is no longer maintained.", + DeprecationWarning, stacklevel=2) def setup(app): app.add_directive('autosummary', autosummary_directive, True, (0, 0, False), |