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

* 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 <[email protected]>

Author: rossbar

.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:

.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

.gitmodules

@@ -1,3 +0,0 @@
-[submodule "doc/scipy-sphinx-theme"]
-	path = doc/scipy-sphinx-theme
-	url = https://github.com/scipy/scipy-sphinx-theme

doc/conf.py

@@ -99,7 +99,7 @@
 
 # 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 @@
 # 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'

doc/example.rst

@@ -1,4 +1,3 @@
-
 .. _example:
 
 =======

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:

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

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``:
 

doc/requirements.txt

@@ -1,2 +1,3 @@
 numpy
 matplotlib
+pydata-sphinx-theme

doc/scipy-sphinx-theme

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