diff options
author | Ross Barnowski <rossbar@berkeley.edu> | 2021-02-26 11:22:59 -0800 |
---|---|---|
committer | GitHub <noreply@github.com> | 2021-02-26 14:22:59 -0500 |
commit | 5ca63a70c8706c294e6c5db70782e817719a2a78 (patch) | |
tree | a5eba35d070b42735696cd3a685c1d48feafda01 /doc | |
parent | bdda0567122f0640e50dfd810b88fbd5a93de8e9 (diff) | |
download | numpydoc-5ca63a70c8706c294e6c5db70782e817719a2a78.tar.gz |
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>
Diffstat (limited to 'doc')
-rw-r--r-- | doc/conf.py | 37 | ||||
-rw-r--r-- | doc/example.rst | 1 | ||||
-rw-r--r-- | doc/format.rst | 11 | ||||
-rw-r--r-- | doc/index.rst | 9 | ||||
-rw-r--r-- | doc/install.rst | 16 | ||||
-rw-r--r-- | doc/requirements.txt | 1 | ||||
m--------- | doc/scipy-sphinx-theme | 0 | ||||
-rw-r--r-- | doc/validation.rst | 9 |
8 files changed, 33 insertions, 51 deletions
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: |