Merge branch 'main' into see-more-accepts-sphinx-crosslinks

Author: j9ac9k

.github/workflows/main.yml

@@ -5,7 +5,7 @@ jobs:
     name: Run CircleCI artifacts redirector
     steps:
       - name: GitHub Action step
-        uses: larsoner/circleci-artifacts-redirector-action@master
+        uses: scientific-python/circleci-artifacts-redirector-action@4e13a10d89177f4bfc8007a7064bdbeda848d8d1 # v1.0.0
         with:
           repo-token: ${{ secrets.GITHUB_TOKEN }}
           api-token: ${{ secrets.CIRCLECI_ARTIFACT_REDIRECTOR_TOKEN }}

.github/workflows/release.yml

@@ -1,34 +1,47 @@
 name: Build Wheel and Release
 on:
+  pull_request:
+    branches:
+      - main
   push:
     tags:
       - v*
 
 jobs:
-  pypi-publish:
-    name: upload release to PyPI
-    if: github.repository_owner == 'numpy' && startsWith(github.ref, 'refs/tags/v') && github.actor == 'jarrodmillman' && always()
+  sdist_wheel:
+    name: sdist and wheels
     runs-on: ubuntu-latest
-    # Specifying a GitHub environment is optional, but strongly encouraged
-    environment: release
-    permissions:
-      # IMPORTANT: this permission is mandatory for trusted publishing
-      id-token: write
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
         with:
           fetch-depth: 0
-
-      - uses: actions/setup-python@v5
-        name: Install Python
+      - uses: actions/setup-python@39cd14951b08e74b54015e9e001cdefcf80e669f # v5.1.1
         with:
           python-version: "3.12"
-
       - name: Build wheels
         run: |
           git clean -fxd
           pip install -U build twine wheel
           python -m build --sdist --wheel
+      - run: twine check --strict dist/*
+      - uses: actions/upload-artifact@65c4c4a1ddee5b72f698fdd19549f0f0fb45cf08 # v4.6.0
+        with:
+          name: dist
+          path: dist
 
-      - name: Publish package distributions to PyPI
-        uses: pypa/gh-action-pypi-publish@release/v1
+  pypi-publish:
+    needs: sdist_wheel
+    name: upload release to PyPI
+    if: github.repository_owner == 'numpy' && startsWith(github.ref, 'refs/tags/v') && github.actor == 'jarrodmillman' && always()
+    runs-on: ubuntu-latest
+    # Specifying a GitHub environment is optional, but strongly encouraged
+    environment: release
+    permissions:
+      # IMPORTANT: this permission is mandatory for trusted publishing
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@fa0a91b85d4f404e444e00e005971372dc801d16 # v4.1.8
+        with:
+          name: dist
+          path: dist
+      - uses: pypa/gh-action-pypi-publish@76f52bc884231f62b9a034ebfe128415bbaabdfc # v1.12.4

.github/workflows/test.yml

@@ -16,7 +16,7 @@ jobs:
     strategy:
       matrix:
         os: [Ubuntu]
-        python-version: ["3.9", "3.10", "3.11", "3.12"]
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
         sphinx-version:
           ["sphinx==6.0", "sphinx==6.2", "sphinx==7.0", "sphinx>=7.3"]
         include:
@@ -37,14 +37,13 @@ jobs:
       - name: Setup environment
         run: |
           python -m pip install --upgrade pip wheel setuptools
-          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: Install
         run: |
-          python -m pip install .
+          python -m pip install .[test,doc]
           pip list
 
       - name: Run test suite
@@ -79,7 +78,7 @@ jobs:
     strategy:
       matrix:
         os: [ubuntu]
-        python-version: ["3.11", "3.12"]
+        python-version: ["3.11", "3.12", "3.13"]
     steps:
       - uses: actions/checkout@v4
 
@@ -91,13 +90,12 @@ jobs:
       - name: Setup environment
         run: |
           python -m pip install --upgrade pip wheel setuptools
-          python -m pip install --pre -r requirements/test.txt -r requirements/doc.txt
           python -m pip install codecov
           python -m pip list
 
       - name: Install
         run: |
-          python -m pip install .
+          python -m pip install .[test,doc]
           pip list
 
       - name: Run test suite

.gitignore

@@ -16,3 +16,4 @@ doc/_build
 numpydoc/tests/tinybuild/_build
 numpydoc/tests/tinybuild/generated
 MANIFEST
+node_modules

.pre-commit-config.yaml

@@ -3,7 +3,7 @@
 
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: 2c9f875913ee60ca25ce70243dc24d5b6415598c # frozen: v4.6.0
+    rev: cef0300fd0fc4d2a87a85fa2093c6b283ea36f4b # frozen: v5.0.0
     hooks:
       - id: check-added-large-files
       - id: check-ast
@@ -18,14 +18,14 @@ repos:
       - id: trailing-whitespace
 
   - repo: https://github.com/pre-commit/mirrors-prettier
-    rev: ffb6a759a979008c0e6dff86e39f4745a2d9eac4 # frozen: v3.1.0
+    rev: f12edd9c7be1c20cfa42420fd0e6df71e42b51ea # frozen: v4.0.0-alpha.8
     hooks:
       - id: prettier
         types_or: [yaml, toml, markdown, css, scss, javascript, json]
         args: [--prose-wrap=preserve]
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: "f8a3f8c471fb698229face5ed7640a64900b781e" # frozen: v0.4.4
+    rev: "89c421dff2e1026ba12cdb9ebd731f4a83aa8021" # frozen: v0.8.6
     hooks:
       - id: ruff
         args: ["--fix", "--show-fixes", "--exit-non-zero-on-fix"]

.readthedocs.yaml

@@ -6,9 +6,9 @@ version: 2
 
 # Set the OS, Python version and other tools you might need
 build:
-  os: ubuntu-22.04
+  os: ubuntu-24.04
   tools:
-    python: "3.11"
+    python: "3.13"
     # You can also specify other tool versions:
     # nodejs: "19"
     # rust: "1.64"

README.rst

@@ -4,7 +4,6 @@ numpydoc -- Numpy's Sphinx extensions
 
 .. image:: https://readthedocs.org/projects/numpydoc/badge/?version=latest
    :alt: Documentation Status
-   :scale: 100%
    :target: https://numpydoc.readthedocs.io/en/latest/
 
 .. image:: https://codecov.io/gh/numpy/numpydoc/branch/main/graph/badge.svg

doc/conf.py

@@ -12,6 +12,8 @@
 import sys
 from datetime import date
 
+from intersphinx_registry import get_intersphinx_mapping
+
 import numpydoc
 
 # for example.py
@@ -80,7 +82,7 @@
 html_theme = "pydata_sphinx_theme"
 html_theme_options = {
     "show_prev_next": False,
-    "navbar_end": ["theme-switcher", "search-field.html", "navbar-icon-links.html"],
+    "navbar_end": ["theme-switcher", "navbar-icon-links.html"],
     "icon_links": [
         {
             "name": "GitHub",
@@ -136,9 +138,6 @@
 
 # -- Intersphinx setup ----------------------------------------------------
 
-# Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {
-    "python": ("https://docs.python.org/3/", None),
-    "numpy": ("https://numpy.org/devdocs/", None),
-    "sklearn": ("https://scikit-learn.org/stable/", None),
-}
+# Example configuration for intersphinx: refer to several Python libraries.
+
+intersphinx_mapping = get_intersphinx_mapping(packages=["python", "numpy", "sklearn"])

doc/format.rst

@@ -175,8 +175,9 @@ respective types.
   y
       Description of parameter `y` (with type not specified).
 
-Enclose variables in single backticks.  The colon must be preceded
-by a space, or omitted if the type is absent.
+The colon must be preceded by a space, or omitted if the type is absent.
+When referring to a parameter anywhere within the docstring, enclose its
+name in single backticks.
 
 For the parameter types, be as precise as possible.  Below are a
 few examples of parameters and their types.
@@ -224,11 +225,11 @@ description, they can be combined::
       Input arrays, description of `x1`, `x2`.
 
 When documenting variable length positional, or keyword arguments, leave the
-leading star(s) in front of the name::
+leading star(s) in front of the name and do not specify a type::
 
-  *args : tuple
+  *args
       Additional arguments should be passed as keyword arguments
-  **kwargs : dict, optional
+  **kwargs
       Extra arguments to `metric`: refer to each metric documentation for a
       list of all possible arguments.
 
@@ -549,23 +550,29 @@ not explicitly imported, `.. plot::` can be used directly if
 Documenting classes
 -------------------
 
+.. _classdoc:
+
 Class docstring
 ```````````````
 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.
+constructor's parameters. While repetition is unnecessary, a docstring for
+the class constructor (``__init__``) can, optionally, be added to provide
+detailed initialization documentation.
 
 An **Attributes** section, located below the :ref:`Parameters <params>`
 section, may be used to describe non-method attributes of the class::
 
   Attributes
   ----------
   x : float
-      The X coordinate.
+      Description of attribute `x`.
   y : float
-      The Y coordinate.
+      Description of attribute `y`.
 
+When referring to an attribute anywhere within the docstring, enclose its
+name in single backticks.
 Attributes that are properties and have their own docstrings can be
 simply listed by name::
 
@@ -606,6 +613,8 @@ becomes useful to have an additional **Methods** section:
 
       """
 
+When referring to a method anywhere within the docstring, enclose its
+name in single backticks.
 If it is necessary to explain a private method (use with care!), it can
 be referred to in the :ref:`Extended Summary <extended_summary>` or the
 :ref:`Notes <notes>` section.
@@ -690,11 +699,11 @@ belong in docstrings.
 Other points to keep in mind
 ----------------------------
 * Equations : as discussed in the :ref:`Notes <notes>` section above, LaTeX
-  formatting should be kept to a minimum.  Often it's possible to show equations as
-  Python code or pseudo-code instead, which is much more readable in a
-  terminal.  For inline display use double backticks (like ``y = np.sin(x)``).
-  For display with blank lines above and below, use a double colon and indent
-  the code, like::
+  formatting should be kept to a minimum.  Often it's possible to show
+  equations as Python code or pseudo-code instead, which is much more readable
+  in a terminal.  For inline display of code, use double backticks
+  like ````y = np.sin(x)````. For display with blank lines above and below,
+  use a double colon and indent the code, like::
 
     end of previous sentence::
 
@@ -717,9 +726,13 @@ Other points to keep in mind
   (i.e. scalar types, sequence types), those arguments can be documented
   with type `array_like`.
 
-* Links : If you need to include hyperlinks in your docstring, note that
-  some docstring sections are not parsed as standard reST, and in these
-  sections, numpydoc may become confused by hyperlink targets such as::
+* Links : Depending on project settings, hyperlinks to documentation of
+  modules, classes, functions, methods, and attributes should automatically
+  be created if a recognized name is included within single backticks (e.g.
+  ```numpy``` renders as :any:`numpy`). If you need to include other
+  hyperlinks, note that some docstring sections are not parsed as standard
+  reST, and in these sections, numpydoc may become confused by hyperlink
+  targets such as::
 
       .. _Example: http://www.example.com
 
@@ -729,17 +742,31 @@ Other points to keep in mind
 
       `Example <http://www.example.com>`_
 
-
 Common reST concepts
 --------------------
 For paragraphs, indentation is significant and indicates indentation in the
 output. New paragraphs are marked with a blank line.
 
-Use ``*italics*``, ``**bold**`` and ````monospace```` if needed in any
-explanations
-(but not for variable names and doctest code or multi-line code).
-Variable, module, function, and class names should be written between
-single back-ticks (```numpy```).
+Use ``*italics*``, ``**bold**`` if needed in any explanations.
+
+Use of backticks in reST is a common point of confusion because it is different
+from markdown. In most flavors of markdown, single backticks are used for
+monospaced font; in reST, *double* backticks are for ``monospaced font``,
+whereas the behavior of single backticks is defined by the default role. This
+leads to the following style recommendations:
+
+- Module, class, function, method, and attribute names should render as
+  hyperlinks in monospaced font (e.g. :any:`numpy`); depending on project
+  settings, this may be accomplished simply be enclosing them in single
+  backticks. If the hyperlink does not render as intended, explicitly
+  include the appropriate role and/or namespace.
+- This guide continues to recommended that parameter names be enclosed within
+  single backticks. Currently, this may cause parameter names to render
+  improperly and cause warnings, but numpydoc will soon release a feature
+  that causes them to render as monospaced hyperlinks to the parameter
+  documentation.
+- All other text that is intended to render in ``monospaced`` font should be
+  enclosed within ````double backticks````.
 
 A more extensive example of reST markup can be found in `this example
 document <http://docutils.sourceforge.net/docs/user/rst/demo.txt>`_;

doc/install.rst

@@ -9,6 +9,7 @@ This extension requires Python 3.9+, sphinx 6+ and is available from:
 
 * `numpydoc on PyPI <http://pypi.python.org/pypi/numpydoc>`_
 * `numpydoc on GitHub <https://github.com/numpy/numpydoc/>`_
+* `numpydoc on conda-forge <https://prefix.dev/channels/conda-forge/packages/numpydoc>`_
 
 `'numpydoc'` should be added to the ``extensions`` option in your Sphinx
 ``conf.py``. ``'sphinx.ext.autosummary'`` will automatically be loaded