Merge branch 'numpy:main' into main

Author: guillaumedavidphd

.circleci/config.yml

@@ -2,39 +2,47 @@ version: 2
 jobs:
   build_docs:
     docker:
-      - image: circleci/python:3.7-stretch
+      - image: "cimg/python:3.10"
     steps:
       - checkout
       - run:
-          name: Set BASH_ENV
-          command: |
-            echo "set -e" >> $BASH_ENV;
-            echo "export PATH=~/.local/bin:$PATH" >> $BASH_ENV;
-            sudo apt update
-            sudo apt install dvipng texlive-fonts-recommended texlive-latex-recommended texlive-latex-extra texlive-generic-extra latexmk texlive-xetex
+          name: Update apt-get
+          command: sudo apt-get update
+      - run:
+          name: Install TeX
+          command: sudo apt install dvipng texlive-fonts-recommended texlive-latex-recommended texlive-latex-extra latexmk texlive-xetex
       - restore_cache:
           keys:
             - pip-cache
       - run:
           name: Get dependencies and install
           command: |
-            pip install --user -q --upgrade pip setuptools
-            pip install --user -q --upgrade numpy matplotlib sphinx pydata-sphinx-theme
-            pip install --user -e .
+            python3 -m venv venv
+            source venv/bin/activate
+            python -m pip install --upgrade pip wheel setuptools
+            python -m pip install --upgrade -r requirements/doc.txt
+            python -m pip list
       - save_cache:
           key: pip-cache
           paths:
             - ~/.cache/pip
       - run:
-          name: make html
+          name: Install
+          command: |
+            source venv/bin/activate
+            pip install -e .
+      - run:
+          name: Build docs
           command: |
+            source venv/bin/activate
             make -C doc html
       - store_artifacts:
           path: doc/_build/html/
           destination: html
       - run:
           name: make tinybuild
           command: |
+            source venv/bin/activate
             make -C numpydoc/tests/tinybuild html
       - store_artifacts:
           path: numpydoc/tests/tinybuild/_build/html/

.github/workflows/lint.yml

@@ -8,5 +8,5 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v3
-      - uses: actions/setup-python@v3
-      - uses: pre-commit/action@v2.0.3
+      - uses: actions/setup-python@v4
+      - uses: pre-commit/action@v3.0.0

.github/workflows/test.yml

@@ -12,36 +12,33 @@ jobs:
     strategy:
       matrix:
         os: [Ubuntu]
-        python-version: ["3.7", "3.8", "3.9", "3.10"]
-        sphinx-version: ["sphinx==3.0", "sphinx==4.0", "sphinx>4.4"]
+        python-version: ["3.7", "3.8", "3.9", "3.10", "3.11-dev"]
+        sphinx-version:
+          ["sphinx==4.2", "sphinx==4.5", "sphinx==5.0", "sphinx>=5.0"]
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
 
       - name: Python setup
-        uses: actions/setup-python@v2
+        uses: actions/setup-python@v4
         with:
           python-version: ${{ matrix.python-version }}
 
       - name: Setup environment
         run: |
           python -m pip install --upgrade pip wheel setuptools
-          python -m pip install -r requirements/test.txt -r doc/requirements.txt
+          python -m pip install -r requirements/test.txt -r requirements/doc.txt
           python -m pip install codecov
           python -m pip install ${{ matrix.sphinx-version }}
           python -m pip list
 
-      - name: Downgrade Jinja2 for sphinx<4
-        if: ${{ matrix.sphinx-version }} == 'sphinx<4.0.2'
-        run: python -m pip install jinja2==3.0.3 markupsafe==2.0.1 pydata-sphinx-theme==0.8.0
-
       - name: Install
         run: |
           python -m pip install .
           pip list
 
       - name: Run test suite
         run: |
-          pytest -v --pyargs .
+          pytest -v --pyargs numpydoc
 
       - name: Test coverage
         run: |
@@ -64,67 +61,24 @@ jobs:
           make -C doc html SPHINXOPTS="-nT"
           make -C doc latexpdf SPHINXOPTS="-nT"
 
-  base:
-    runs-on: ${{ matrix.os }}-latest
-    strategy:
-      matrix:
-        os: [ubuntu, macos, windows]
-        python-version: ["3.11-dev"]
-        sphinx-version: ["sphinx==4.0", "sphinx==4.5"]
-    steps:
-      - uses: actions/checkout@v2
-
-      - name: Python setup
-        uses: actions/setup-python@v2
-        with:
-          python-version: ${{ matrix.python-version }}
-
-      - name: Setup environment
-        run: |
-          python -m pip install --upgrade pip wheel setuptools
-          python -m pip install pytest pytest-cov
-          python -m pip install ${{ matrix.sphinx-version }}
-          python -m pip list
-
-      - name: Downgrade Jinja2 for sphinx<4
-        if: ${{ matrix.sphinx-version }} == 'sphinx<4.0.2'
-        run: python -m pip install jinja2==3.0.3 markupsafe==2.0.1 pydata-sphinx-theme==0.8.0
-
-      - name: Install
-        run: |
-          python -m pip install .
-          pip list
-
-      - name: Run test suite
-        run: |
-          pytest -v --pyargs numpydoc
-
-      - name: Make sure CLI works
-        run: |
-          python -m numpydoc numpydoc.tests.test_main._capture_stdout
-          echo '! python -m numpydoc numpydoc.tests.test_main._invalid_docstring' | bash
-          python -m numpydoc --validate numpydoc.tests.test_main._capture_stdout
-          echo '! python -m numpydoc --validate numpydoc.tests.test_main._docstring_with_errors' | bash
-
   prerelease:
     runs-on: ${{ matrix.os }}-latest
     strategy:
       matrix:
         os: [ubuntu]
         python-version: ["3.9", "3.10"]
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
 
       - name: Python setup
-        uses: actions/setup-python@v2
+        uses: actions/setup-python@v4
         with:
           python-version: ${{ matrix.python-version }}
 
       - name: Setup environment
         run: |
           python -m pip install --upgrade pip wheel setuptools
-          python -m pip install --pre -r requirements/test.txt -r doc/requirements.txt
-          python -m pip install docutils==0.17.1  # FIXME
+          python -m pip install --pre -r requirements/test.txt -r requirements/doc.txt
           python -m pip install codecov
           python -m pip list
 

.pre-commit-config.yaml

@@ -3,7 +3,7 @@
 
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.2.0
+    rev: v4.3.0
     hooks:
       - id: trailing-whitespace
       - id: end-of-file-fixer
@@ -17,12 +17,12 @@ repos:
       - id: check-added-large-files
 
   - repo: https://github.com/psf/black
-    rev: 22.3.0
+    rev: 22.8.0
     hooks:
       - id: black
 
   - repo: https://github.com/pre-commit/mirrors-prettier
-    rev: v2.6.2
+    rev: v2.7.1
     hooks:
       - id: prettier
         files: \.(html|md|yml|yaml)
@@ -34,7 +34,7 @@ repos:
       - id: blacken-docs
 
   - repo: https://github.com/asottile/pyupgrade
-    rev: v2.32.1
+    rev: v2.38.2
     hooks:
       - id: pyupgrade
         args: [--py37-plus]

README.rst

@@ -18,7 +18,7 @@ docstrings formatted according to the NumPy documentation format.
 The extension also adds the code description directives
 ``np:function``, ``np-c:function``, etc.
 
-numpydoc requires Python 3.7+ and sphinx 3.0+.
+numpydoc requires Python 3.7+ and sphinx 4.2+.
 
 For usage information, please refer to the `documentation
 <https://numpydoc.readthedocs.io/>`_.

doc/conf.py

@@ -85,9 +85,26 @@
     "show_prev_next": False,
     "navbar_end": ["search-field.html", "navbar-icon-links.html"],
 }
+# NOTE: The following is required for supporting of older sphinx toolchains.
+#       The "theme-switcher" templated should be added directly to navbar_end
+#       above and the following lines removed when the minimum supported
+#       version of pydata_sphinx_theme is 0.9.0
+# Add version switcher for versions of pydata_sphinx_theme that support it
+import packaging
+import pydata_sphinx_theme
+
+if packaging.version.parse(pydata_sphinx_theme.__version__) >= packaging.version.parse(
+    "0.9.0"
+):
+    html_theme_options["navbar_end"].insert(0, "theme-switcher")
+
+
 html_sidebars = {
     "**": [],
 }
+html_context = {
+    "default_mode": "light",
+}
 
 html_title = f"{project} v{version} Manual"
 html_last_updated_fmt = "%b %d, %Y"

doc/format.rst

@@ -31,7 +31,7 @@ Use a code checker:
  * pyflakes_: a tool to check Python code for errors by parsing
    the source file instead of importing it.
  * pycodestyle_: (formerly ``pep8``) a tool to check Python code against
-   some of the style conventions in PEP 8.
+   some of the style conventions in :pep:`8`.
  * flake8_: a tool that glues together ``pycodestyle``, ``pyflakes``,
    ``mccabe`` to check the style and quality of Python code.
  * vim-flake8_: a ``flake8`` plugin for Vim.
@@ -287,14 +287,18 @@ takes the same form as the :ref:`Returns <returns>` section::
 Support for the :ref:`Yields <yields>` section was added in `numpydoc
 <https://github.com/numpy/numpydoc>`_ version 0.6.
 
+.. _receives:
+
 7. Receives
 ```````````
 
 Explanation of parameters passed to a generator's ``.send()`` method,
-formatted as for Parameters, above.  Since, like for Yields and Returns, a
-single object is always passed to the method, this may describe either the
-single parameter, or positional arguments passed as a tuple.  If a docstring
-includes Receives it must also include Yields.
+formatted as for :ref:`Parameters <params>`, above.  Since, like for
+:ref:`Yields <yields>` and :ref:`Returns <returns>`, a single object is
+always passed to the method, this may describe either the single parameter,
+or positional arguments passed as a tuple.  If a docstring
+includes :ref:`Receives <receives>` it must also include
+:ref:`Yields <yields>`.
 
 8. Other Parameters
 ```````````````````
@@ -303,6 +307,8 @@ An optional section used to describe infrequently used parameters.
 It should only be used if a function has a large number of keyword
 parameters, to prevent cluttering the :ref:`Parameters <params>` section.
 
+.. _raises:
+
 9. Raises
 `````````
 
@@ -321,7 +327,7 @@ that are non-obvious or have a large chance of getting raised.
 `````````
 
 An optional section detailing which warnings get raised and
-under what conditions, formatted similarly to Raises.
+under what conditions, formatted similarly to :ref:`Raises <raises>`.
 
 11. Warnings
 ````````````
@@ -545,8 +551,8 @@ Documenting classes
 
 Class docstring
 ```````````````
-Use the same sections as outlined above (all except ``Returns`` are
-applicable).  The constructor (``__init__``) should also be documented
+Use the same sections as outlined above (all except :ref:`Returns <returns>`
+are applicable).  The constructor (``__init__``) should also be documented
 here, the :ref:`Parameters <params>` section of the docstring details the
 constructor's parameters.
 

doc/index.rst

@@ -1,3 +1,5 @@
+:html_theme.sidebar_secondary.remove: true
+
 =====================================
 numpydoc -- Numpy's Sphinx extensions
 =====================================

doc/install.rst

@@ -5,7 +5,7 @@ Getting started
 Installation
 ============
 
-This extension requires Python 3.7+, sphinx 3.0+ and is available from:
+This extension requires Python 3.7+, sphinx 4.2+ and is available from:
 
 * `numpydoc on PyPI <http://pypi.python.org/pypi/numpydoc>`_
 * `numpydoc on GitHub <https://github.com/numpy/numpydoc/>`_
@@ -26,10 +26,18 @@ numpydoc_show_class_members : bool
   Whether to show all members of a class in the Methods and Attributes
   sections automatically.
   ``True`` by default.
-numpydoc_show_inherited_class_members : bool
+numpydoc_show_inherited_class_members : bool | dict
   Whether to show all inherited members of a class in the Methods and Attributes
   sections automatically. If it's false, inherited members won't shown.
-  ``True`` by default.
+  ``True`` by default. It can also be a dict mapping names of classes to
+  boolean values (missing keys are treated as ``True``).
+  For example, ``defaultdict(lambda: False, {'mymod.MyClass': True})``
+  would only show inherited class members for ``MyClass``, whereas
+  ``{'mymod.MyClass': False}`` would show inherited class members for all
+  classes except ``MyClass``. Note that disabling this for a limited set of
+  classes might simultaneously require the use of a separate, custom
+  autosummary class template with ``:no-inherited-members:`` in the
+  ``autoclass`` directive options.
 numpydoc_class_members_toctree : bool
   Whether to create a Sphinx table of contents for the lists of class
   methods and attributes. If a table of contents is made, Sphinx expects
@@ -40,10 +48,6 @@ numpydoc_citation_re : str
   should be mangled to avoid conflicts due to
   duplication across the documentation.  Defaults
   to ``[\w-]+``.
-numpydoc_use_blockquotes : bool
-  Until version 0.8, parameter definitions were shown as blockquotes, rather
-  than in a definition list.  If your styling requires blockquotes, switch
-  this config option to True.  This option will be removed in version 0.10.
 numpydoc_attributes_as_param_list : bool
   Whether to format the Attributes section of a class page in the same way
   as the Parameter section. If it's False, the Attributes section will be