DOC: Switch docs to pydata-sphinx-theme (#313)master

* Rm scipy-sphinx-theme submodule.

* Add pydata-sphinx-theme to doc reqs.

* Modify conf to use pydata theme.

* Add github badge via theme.

* Update CI.

* bump CI sphinx version 1.6.5 -> 1.8 for tests

* Experimental: swap sidebars in theme.

* Add :notoc: to index to suppress right sidebar.

* FIX: No sidebar

Co-authored-by: Eric Larson <larson.eric.d@gmail.com>

11 files changed, 35 insertions, 60 deletions

diff --git a/.circleci/config.yml b/.circleci/config.yml
index 7a16e7b..10a53a0 100644
--- a/.circleci/config.yml
+++ b/.circleci/config.yml
@@ -18,10 +18,8 @@ jobs:
             name: Get dependencies and install
             command: |
               pip install --user -q --upgrade pip setuptools
-              pip install --user -q --upgrade numpy matplotlib sphinx
+              pip install --user -q --upgrade numpy matplotlib sphinx pydata-sphinx-theme
               pip install --user -e .
-              git submodule init
-              git submodule update
         - save_cache:
             key: pip-cache
             paths:
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index c6eafc5..67e2522 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -13,7 +13,7 @@ jobs:
       matrix:
         os: [Ubuntu]
         python-version: [3.6, 3.7, 3.8, 3.9]
-        sphinx-version: ["sphinx==1.6.5", "sphinx==2.1", "sphinx>3.0"]
+        sphinx-version: ["sphinx==1.8.0", "sphinx==2.1", "sphinx>3.0"]
     steps:
     - uses: actions/checkout@v2
     
@@ -53,8 +53,6 @@ jobs:
 
     - name: Setup for doc build
       run: |
-        # Get scipy-sphinx-theme
-        git submodule update --init
         sudo apt install texlive texlive-latex-extra latexmk dvipng
 
     - name: Build documentation
diff --git a/.gitmodules b/.gitmodules
index 2ab4876..e69de29 100644
--- a/.gitmodules
+++ b/.gitmodules
@@ -1,3 +0,0 @@
-[submodule "doc/scipy-sphinx-theme"]
-	path = doc/scipy-sphinx-theme
-	url = https://github.com/scipy/scipy-sphinx-theme
diff --git a/doc/conf.py b/doc/conf.py
index 185b6b1..1f39b91 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -99,7 +99,7 @@ numpydoc_validation_checks = {"all", "GL01", "SA04", "RT03"}
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-exclude_patterns = ['_build', 'scipy-sphinx-theme']
+exclude_patterns = ['_build']
 
 # The reST default role (used for this markup: `text`) to use for all
 # documents.
@@ -131,32 +131,15 @@ pygments_style = 'sphinx'
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 
-themedir = os.path.join(os.path.dirname(__file__), 'scipy-sphinx-theme', '_theme')
-if not os.path.isdir(themedir):
-    raise RuntimeError("Get the scipy-sphinx-theme first, "
-                       "via git submodule init && git submodule update")
-
-html_theme = 'scipy'
-html_theme_path = [themedir]
-
-if 'scipyorg' in tags:  # noqa: F821
-    # Build for the scipy.org website
-    html_theme_options = {
-        "edit_link": True,
-        "sidebar": "right",
-        "scipy_org_logo": True,
-        "rootlinks": [("https://scipy.org/", "Scipy.org"),
-                      ("https://docs.scipy.org/", "Docs")]
-    }
-else:
-    # Default build
-    html_theme_options = {
-        "edit_link": False,
-        "sidebar": "left",
-        "scipy_org_logo": False,
-        "rootlinks": []
-    }
-    html_sidebars = {}
+html_theme = "pydata_sphinx_theme"
+html_theme_options = {
+    "github_url": "https://github.com/numpy/numpydoc",
+    "show_prev_next": False,
+    "search_bar_position": "navbar",
+}
+html_sidebars = {
+    "**": [],
+}
 
 html_title = "%s v%s Manual" % (project, version)
 html_last_updated_fmt = '%b %d, %Y'
diff --git a/doc/example.rst b/doc/example.rst
index ae0f25d..0c6adfb 100644
--- a/doc/example.rst
+++ b/doc/example.rst
@@ -1,4 +1,3 @@
-
 .. _example:
 
 =======
diff --git a/doc/format.rst b/doc/format.rst
index 173dd5c..f0f29d1 100644
--- a/doc/format.rst
+++ b/doc/format.rst
@@ -1,11 +1,8 @@
-
 .. _format:
 
-========================
-numpydoc docstring guide
-========================
-
-.. Contents::
+===========
+Style guide
+===========
 
 This document describes the syntax and best practices for docstrings used with
 the numpydoc extension for Sphinx_.
@@ -352,7 +349,7 @@ The sections of a function's docstring are:
     code, possibly including a discussion of the algorithm. This
     section may include mathematical equations, written in
     `LaTeX <https://www.latex-project.org/>`_ format::
-    
+
       Notes
       -----
       The FFT is a fast implementation of the discrete Fourier transform:
diff --git a/doc/index.rst b/doc/index.rst
index 05e01ea..05f0546 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -15,14 +15,11 @@ Sphinx, and adds the code description directives ``np:function``,
 - PyPI: https://pypi.python.org/pypi/numpydoc/
 
 
-Documentation
-=============
-
 .. toctree::
-    :maxdepth: 2
+    :hidden:
 
     install
-    release_notes
     format
-    example
     validation
+    release_notes
+    example
diff --git a/doc/install.rst b/doc/install.rst
index 82c7d6b..df3ea71 100644
--- a/doc/install.rst
+++ b/doc/install.rst
@@ -1,19 +1,21 @@
+===============
+Getting started
+===============
 
-============
 Installation
 ============
 
-This extension requires Python 3.5+, sphinx 1.6.5+ and is available from:
+This extension requires Python 3.5+, sphinx 1.8+ and is available from:
 
 * `numpydoc on PyPI <http://pypi.python.org/pypi/numpydoc>`_
 * `numpydoc on GitHub <https://github.com/numpy/numpydoc/>`_
 
-'numpydoc' should be added to the ``extensions`` option in your Sphinx
-``conf.py``. (Note that `sphinx.ext.autosummary` will automatically be loaded
-as well.)
+`'numpydoc'` should be added to the ``extensions`` option in your Sphinx
+``conf.py``. ``'sphinx.ext.autosummary'`` will automatically be loaded
+as well.
 
-Sphinx config options
-=====================
+Configuration
+=============
 
 The following options can be set in your Sphinx ``conf.py``:
 
diff --git a/doc/requirements.txt b/doc/requirements.txt
index aa094d9..2c78865 100644
--- a/doc/requirements.txt
+++ b/doc/requirements.txt
@@ -1,2 +1,3 @@
 numpy
 matplotlib
+pydata-sphinx-theme
diff --git a/doc/scipy-sphinx-theme b/doc/scipy-sphinx-theme
deleted file mode 160000
-Subproject bc3b4b8383d4cd676fe75b7ca8c3e11d6afa8d9
diff --git a/doc/validation.rst b/doc/validation.rst
index 9eacca9..5b82b64 100644
--- a/doc/validation.rst
+++ b/doc/validation.rst
@@ -1,6 +1,9 @@
-==============================
-Validating NumpyDoc docstrings
-==============================
+==========
+Validation
+==========
+
+Docstring Validation using Python
+---------------------------------
 
 To see the Restructured Text generated for an object, the ``numpydoc`` module
 can be called. For example, to do it for ``numpy.ndarray``, use: