Merge pull request #14356 from qwhelan/sphinx

DOC: support and require sphinx>=2.2

4 files changed, 28 insertions, 17 deletions

diff --git a/.circleci/config.yml b/.circleci/config.yml
index b0449b257..772c3fbfd 100644
--- a/.circleci/config.yml
+++ b/.circleci/config.yml
@@ -21,7 +21,7 @@ jobs:
             python3 -m venv venv
             ln -s $(which python3) venv/bin/python3.6
             . venv/bin/activate
-            pip install cython sphinx==1.8.5 matplotlib ipython
+            pip install cython sphinx==2.2.0 matplotlib ipython
             sudo apt-get update
             sudo apt-get install -y graphviz texlive-fonts-recommended texlive-latex-recommended texlive-latex-extra texlive-generic-extra latexmk texlive-xetex
 
diff --git a/azure-pipelines.yml b/azure-pipelines.yml
index a36f65faa..0e97d42d6 100644
--- a/azure-pipelines.yml
+++ b/azure-pipelines.yml
@@ -88,7 +88,7 @@ jobs:
     displayName: 'Install tools'
   - script: |
       python -m pip install -r test_requirements.txt
-      python -m pip install vulture docutils sphinx==1.8.5 numpydoc
+      python -m pip install vulture docutils sphinx==2.2.0 numpydoc
     displayName: 'Install dependencies; some are optional to avoid test skips'
   - script: /bin/bash -c "! vulture . --min-confidence 100 --exclude doc/,numpy/distutils/ | grep 'unreachable'"
     displayName: 'Check for unreachable code paths in Python modules'
diff --git a/doc/source/_templates/autosummary/base.rst b/doc/source/_templates/autosummary/base.rst
new file mode 100644
index 000000000..0331154a7
--- /dev/null
+++ b/doc/source/_templates/autosummary/base.rst
@@ -0,0 +1,14 @@
+{% if objtype == 'property' %}
+:orphan:
+{% endif %}
+
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+{% if objtype == 'property' %}
+property
+{% endif %}
+
+.. auto{{ objtype }}:: {{ objname }}
+
diff --git a/doc/source/conf.py b/doc/source/conf.py
index 4f312eff5..83cecc917 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -3,12 +3,8 @@ from __future__ import division, absolute_import, print_function
 
 import sys, os, re
 
-# Check Sphinx version
-import sphinx
-if sphinx.__version__ < "1.2.1":
-    raise RuntimeError("Sphinx 1.2.1 or newer required")
-
-needs_sphinx = '1.0'
+# Minimum version, enforced by sphinx
+needs_sphinx = '2.2.0'
 
 # -----------------------------------------------------------------------------
 # General configuration
@@ -31,13 +27,10 @@ extensions = [
     'matplotlib.sphinxext.plot_directive',
     'IPython.sphinxext.ipython_console_highlighting',
     'IPython.sphinxext.ipython_directive',
+    'sphinx.ext.imgmath',
 ]
 
-if sphinx.__version__ >= "1.4":
-    extensions.append('sphinx.ext.imgmath')
-    imgmath_image_format = 'svg'
-else:
-    extensions.append('sphinx.ext.pngmath')
+imgmath_image_format = 'svg'
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -45,6 +38,8 @@ templates_path = ['_templates']
 # The suffix of source filenames.
 source_suffix = '.rst'
 
+master_doc = 'contents'
+
 # General substitutions.
 project = 'NumPy'
 copyright = '2008-2019, The SciPy community'
@@ -93,6 +88,7 @@ pygments_style = 'sphinx'
 def setup(app):
     # add a config value for `ifconfig` directives
     app.add_config_value('python_version_major', str(sys.version_info.major), 'env')
+    app.add_lexer('NumPyC', NumPyLexer(stripnl=False))
 
 # -----------------------------------------------------------------------------
 # HTML output
@@ -177,6 +173,10 @@ latex_documents = [
 # not chapters.
 #latex_use_parts = False
 
+latex_elements = {
+    'fontenc': r'\usepackage[LGR,T1]{fontenc}'
+}
+
 # Additional stuff for the LaTeX preamble.
 latex_preamble = r'''
 \usepackage{amsmath}
@@ -368,18 +368,15 @@ def linkcode_resolve(domain, info):
 
 from pygments.lexers import CLexer
 from pygments import token
-from sphinx.highlighting import lexers
 import copy
 
 class NumPyLexer(CLexer):
     name = 'NUMPYLEXER'
 
-    tokens = copy.deepcopy(lexers['c'].tokens)
+    tokens = copy.deepcopy(CLexer.tokens)
     # Extend the regex for valid identifiers with @
     for k, val in tokens.items():
         for i, v in enumerate(val):
             if isinstance(v, tuple):
                 if isinstance(v[0], str):
                     val[i] =  (v[0].replace('a-zA-Z', 'a-zA-Z@'),) + v[1:]
-
-lexers['NumPyC'] = NumPyLexer(stripnl=False)