From bbf8916ff7994a7f1d5ba321147a90e2f15ac978 Mon Sep 17 00:00:00 2001 From: Ross Barnowski Date: Tue, 23 Feb 2021 16:36:33 -0800 Subject: [PATCH 1/9] Rm scipy-sphinx-theme submodule. --- .gitmodules | 3 --- doc/scipy-sphinx-theme | 1 - 2 files changed, 4 deletions(-) delete mode 160000 doc/scipy-sphinx-theme diff --git a/.gitmodules b/.gitmodules index 2ab48762..e69de29b 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/scipy-sphinx-theme b/doc/scipy-sphinx-theme deleted file mode 160000 index bc3b4b83..00000000 --- a/doc/scipy-sphinx-theme +++ /dev/null @@ -1 +0,0 @@ -Subproject commit bc3b4b8383d4cd676fe75b7ca8c3e11d6afa8d97 From 3ff9e51b1a02d595d2c75bcf3da6ba4a21c9d2b9 Mon Sep 17 00:00:00 2001 From: Ross Barnowski Date: Tue, 23 Feb 2021 16:47:52 -0800 Subject: [PATCH 2/9] Add pydata-sphinx-theme to doc reqs. --- doc/requirements.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/requirements.txt b/doc/requirements.txt index aa094d9f..2c788654 100644 --- a/doc/requirements.txt +++ b/doc/requirements.txt @@ -1,2 +1,3 @@ numpy matplotlib +pydata-sphinx-theme From c0e75f6ed9dc7fac944f5532c3a229a02d035359 Mon Sep 17 00:00:00 2001 From: Ross Barnowski Date: Tue, 23 Feb 2021 16:48:08 -0800 Subject: [PATCH 3/9] Modify conf to use pydata theme. --- doc/conf.py | 29 ++--------------------------- 1 file changed, 2 insertions(+), 27 deletions(-) diff --git a/doc/conf.py b/doc/conf.py index 185b6b18..e81caddb 100644 --- a/doc/conf.py +++ b/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,7 @@ # 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_title = "%s v%s Manual" % (project, version) html_last_updated_fmt = '%b %d, %Y' From b85939167cdf34bba35d94b15def7c37d3ad4fec Mon Sep 17 00:00:00 2001 From: Ross Barnowski Date: Tue, 23 Feb 2021 16:58:15 -0800 Subject: [PATCH 4/9] Add github badge via theme. --- doc/conf.py | 3 +++ 1 file changed, 3 insertions(+) diff --git a/doc/conf.py b/doc/conf.py index e81caddb..50e9b5e9 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -132,6 +132,9 @@ # a list of builtin themes. html_theme = "pydata_sphinx_theme" +html_theme_options = { + "github_url": "https://github.com/numpy/numpydoc" +} html_title = "%s v%s Manual" % (project, version) html_last_updated_fmt = '%b %d, %Y' From 7f69f6c3cac290430e8b47da9188d518a371c103 Mon Sep 17 00:00:00 2001 From: Ross Barnowski Date: Tue, 23 Feb 2021 17:03:53 -0800 Subject: [PATCH 5/9] Update CI. --- .circleci/config.yml | 4 +--- .github/workflows/test.yml | 2 -- 2 files changed, 1 insertion(+), 5 deletions(-) diff --git a/.circleci/config.yml b/.circleci/config.yml index 7a16e7bc..10a53a0e 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 c6eafc57..07248d00 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -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 From 3db383aa3302181d12b63d82247a9f8eeab528b2 Mon Sep 17 00:00:00 2001 From: Ross Barnowski Date: Tue, 23 Feb 2021 17:16:45 -0800 Subject: [PATCH 6/9] bump CI sphinx version 1.6.5 -> 1.8 for tests --- .github/workflows/test.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 07248d00..67e25221 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 From 0fd85066a62d0f22615536000dadf12df6b7fdd3 Mon Sep 17 00:00:00 2001 From: Ross Barnowski Date: Thu, 25 Feb 2021 15:57:43 -0800 Subject: [PATCH 7/9] Experimental: swap sidebars in theme. --- doc/conf.py | 5 ++++- doc/example.rst | 4 ++++ doc/format.rst | 4 ++++ doc/install.rst | 4 ++++ doc/release_notes.rst | 5 +++++ doc/validation.rst | 5 +++++ 6 files changed, 26 insertions(+), 1 deletion(-) diff --git a/doc/conf.py b/doc/conf.py index 50e9b5e9..ba876e56 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -133,11 +133,14 @@ html_theme = "pydata_sphinx_theme" html_theme_options = { - "github_url": "https://github.com/numpy/numpydoc" + "github_url": "https://github.com/numpy/numpydoc", } html_title = "%s v%s Manual" % (project, version) html_last_updated_fmt = '%b %d, %Y' +html_sidebars = { + "**": ["sidebar-search-bs.html", "docs-toc.html"], +} # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, diff --git a/doc/example.rst b/doc/example.rst index ae0f25d9..b54eafc3 100644 --- a/doc/example.rst +++ b/doc/example.rst @@ -1,3 +1,7 @@ +.. NOTE: The :notoc: metadata is used to suppress the right-sidebar in the + pydata-sphinx-theme. + +:notoc: .. _example: diff --git a/doc/format.rst b/doc/format.rst index 173dd5c2..66f6eed1 100644 --- a/doc/format.rst +++ b/doc/format.rst @@ -1,3 +1,7 @@ +.. NOTE: The :notoc: metadata is used to suppress the right-sidebar in the + pydata-sphinx-theme. + +:notoc: .. _format: diff --git a/doc/install.rst b/doc/install.rst index 82c7d6ba..9a7ff44b 100644 --- a/doc/install.rst +++ b/doc/install.rst @@ -1,3 +1,7 @@ +.. NOTE: The :notoc: metadata is used to suppress the right-sidebar in the + pydata-sphinx-theme. + +:notoc: ============ Installation diff --git a/doc/release_notes.rst b/doc/release_notes.rst index 57cfb550..68ba71cf 100644 --- a/doc/release_notes.rst +++ b/doc/release_notes.rst @@ -1,3 +1,8 @@ +.. NOTE: The :notoc: metadata is used to suppress the right-sidebar in the + pydata-sphinx-theme. + +:notoc: + Release notes ============= diff --git a/doc/validation.rst b/doc/validation.rst index e1b2ee03..9cca1b84 100644 --- a/doc/validation.rst +++ b/doc/validation.rst @@ -1,3 +1,8 @@ +.. NOTE: The :notoc: metadata is used to suppress the right-sidebar in the + pydata-sphinx-theme. + +:notoc: + ============================== Validating NumpyDoc docstrings ============================== From d13b3fbac68dda5644837b6062a45acc5843d27b Mon Sep 17 00:00:00 2001 From: Ross Barnowski Date: Thu, 25 Feb 2021 17:31:47 -0800 Subject: [PATCH 8/9] Add :notoc: to index to suppress right sidebar. --- doc/index.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/doc/index.rst b/doc/index.rst index 05e01ea4..61f1b476 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -1,3 +1,8 @@ +.. NOTE: The :notoc: metadata is used to suppress the right-sidebar in the + pydata-sphinx-theme. + +:notoc: + ===================================== numpydoc -- Numpy's Sphinx extensions ===================================== From 030108cf5db85f79a01213c9fc24e04d3ad691f4 Mon Sep 17 00:00:00 2001 From: Eric Larson Date: Fri, 26 Feb 2021 14:10:55 -0500 Subject: [PATCH 9/9] FIX: No sidebar --- doc/conf.py | 8 +++++--- doc/example.rst | 5 ----- doc/format.rst | 15 ++++----------- doc/index.rst | 14 +++----------- doc/install.rst | 20 +++++++++----------- doc/release_notes.rst | 5 ----- doc/validation.rst | 12 +++++------- 7 files changed, 26 insertions(+), 53 deletions(-) diff --git a/doc/conf.py b/doc/conf.py index ba876e56..1f39b915 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -134,13 +134,15 @@ 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' -html_sidebars = { - "**": ["sidebar-search-bs.html", "docs-toc.html"], -} # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, diff --git a/doc/example.rst b/doc/example.rst index b54eafc3..0c6adfb5 100644 --- a/doc/example.rst +++ b/doc/example.rst @@ -1,8 +1,3 @@ -.. NOTE: The :notoc: metadata is used to suppress the right-sidebar in the - pydata-sphinx-theme. - -:notoc: - .. _example: ======= diff --git a/doc/format.rst b/doc/format.rst index 66f6eed1..f0f29d10 100644 --- a/doc/format.rst +++ b/doc/format.rst @@ -1,15 +1,8 @@ -.. NOTE: The :notoc: metadata is used to suppress the right-sidebar in the - pydata-sphinx-theme. - -:notoc: - .. _format: -======================== -numpydoc docstring guide -======================== - -.. Contents:: +=========== +Style guide +=========== This document describes the syntax and best practices for docstrings used with the numpydoc extension for Sphinx_. @@ -356,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 `_ format:: - + Notes ----- The FFT is a fast implementation of the discrete Fourier transform: diff --git a/doc/index.rst b/doc/index.rst index 61f1b476..05f0546e 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -1,8 +1,3 @@ -.. NOTE: The :notoc: metadata is used to suppress the right-sidebar in the - pydata-sphinx-theme. - -:notoc: - ===================================== numpydoc -- Numpy's Sphinx extensions ===================================== @@ -20,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 9a7ff44b..df3ea71b 100644 --- a/doc/install.rst +++ b/doc/install.rst @@ -1,23 +1,21 @@ -.. NOTE: The :notoc: metadata is used to suppress the right-sidebar in the - pydata-sphinx-theme. +=============== +Getting started +=============== -:notoc: - -============ 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 `_ * `numpydoc on GitHub `_ -'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/release_notes.rst b/doc/release_notes.rst index 68ba71cf..57cfb550 100644 --- a/doc/release_notes.rst +++ b/doc/release_notes.rst @@ -1,8 +1,3 @@ -.. NOTE: The :notoc: metadata is used to suppress the right-sidebar in the - pydata-sphinx-theme. - -:notoc: - Release notes ============= diff --git a/doc/validation.rst b/doc/validation.rst index 9cca1b84..ce6bf255 100644 --- a/doc/validation.rst +++ b/doc/validation.rst @@ -1,11 +1,9 @@ -.. NOTE: The :notoc: metadata is used to suppress the right-sidebar in the - pydata-sphinx-theme. +========== +Validation +========== -:notoc: - -============================== -Validating NumpyDoc docstrings -============================== +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: