Merge branch 'master' into ext-linkcode-allow-builder-to-enable-refer…

…ences

.github/workflows/lint.yml

@@ -83,6 +83,26 @@ jobs:
     - name: Type check with mypy
       run: mypy
 
+  pyright:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3"
+    - name: Install uv
+      run: >
+        curl --no-progress-meter --location --fail
+        --proto '=https' --tlsv1.2
+        "https://astral.sh/uv/install.sh"
+        | sh
+    - name: Install dependencies
+      run: uv pip install ".[lint,test]"
+    - name: Type check with pyright
+      run: pyright
+
   docs-lint:
     runs-on: ubuntu-latest
 

.github/workflows/main.yml

@@ -84,7 +84,7 @@ jobs:
     steps:
     - uses: actions/checkout@v4
     - name: Set up Python ${{ matrix.python }} (deadsnakes)
-      uses: deadsnakes/action@v3.1.0
+      uses: deadsnakes/action@v3.2.0
       with:
         python-version: ${{ matrix.python }}
     - name: Check Python version
@@ -117,7 +117,7 @@ jobs:
     steps:
     - uses: actions/checkout@v4
     - name: Set up Python ${{ matrix.python }} (deadsnakes)
-      uses: deadsnakes/action@v3.1.0
+      uses: deadsnakes/action@v3.2.0
       with:
         python-version: ${{ matrix.python }}
         nogil: true

.github/workflows/transifex.yml

@@ -67,7 +67,7 @@ jobs:
     - name: Compile message catalogs
       run: python utils/babel_runner.py compile
     - name: Create Pull Request
-      uses: peter-evans/create-pull-request@v6
+      uses: peter-evans/create-pull-request@v7
       with:
         add-paths: |
           sphinx/locale

.ruff.toml

@@ -7,7 +7,7 @@ extend-exclude = [
     "tests/js/roots/*",
     "build/*",
     "doc/_build/*",
-    "sphinx/search/*",
+#    "sphinx/search/*",
     "doc/usage/extensions/example*.py",
 ]
 
@@ -411,6 +411,8 @@ select = [
 "sphinx/ext/autodoc/importer.py" = ["D402"]
 "sphinx/util/requests.py" = ["D402"]
 
+"sphinx/search/*" = ["E501"]
+
 "tests/*" = [
     "E501",
     "ANN",  # tests don't need annotations
@@ -442,15 +444,31 @@ forced-separate = [
 preview = true
 quote-style = "single"
 exclude = [
-    "sphinx/_cli/*",
     "sphinx/addnodes.py",
     "sphinx/application.py",
-    "sphinx/builders/*",
-    "sphinx/cmd/*",
+    "sphinx/builders/latex/constants.py",
     "sphinx/config.py",
-    "sphinx/directives/*",
-    "sphinx/domains/*",
-    "sphinx/environment/*",
+    "sphinx/domains/__init__.py",
+    "sphinx/domains/c/_parser.py",
+    "sphinx/domains/c/_ids.py",
+    "sphinx/domains/c/__init__.py",
+    "sphinx/domains/c/_symbol.py",
+    "sphinx/domains/c/_ast.py",
+    "sphinx/domains/changeset.py",
+    "sphinx/domains/citation.py",
+    "sphinx/domains/cpp/_parser.py",
+    "sphinx/domains/cpp/_ids.py",
+    "sphinx/domains/cpp/__init__.py",
+    "sphinx/domains/cpp/_symbol.py",
+    "sphinx/domains/cpp/_ast.py",
+    "sphinx/domains/index.py",
+    "sphinx/domains/javascript.py",
+    "sphinx/domains/math.py",
+    "sphinx/domains/python/_annotations.py",
+    "sphinx/domains/python/__init__.py",
+    "sphinx/domains/python/_object.py",
+    "sphinx/domains/rst.py",
+    "sphinx/domains/std/__init__.py",
     "sphinx/ext/autodoc/__init__.py",
     "sphinx/ext/autodoc/directive.py",
     "sphinx/ext/autodoc/importer.py",
@@ -470,19 +488,9 @@ exclude = [
     "sphinx/ext/imgconverter.py",
     "sphinx/ext/imgmath.py",
     "sphinx/ext/inheritance_diagram.py",
-    "sphinx/ext/intersphinx/*",
     "sphinx/ext/linkcode.py",
     "sphinx/ext/mathjax.py",
-    "sphinx/ext/napoleon/__init__.py",
-    "sphinx/ext/napoleon/docstring.py",
     "sphinx/ext/todo.py",
     "sphinx/ext/viewcode.py",
-    "sphinx/pycode/*",
-    "sphinx/pygments_styles.py",
     "sphinx/registry.py",
-    "sphinx/search/*",
-    "sphinx/testing/*",
-    "sphinx/transforms/*",
-    "sphinx/util/*",
-    "sphinx/writers/*",
 ]

AUTHORS.rst

@@ -72,6 +72,7 @@ Contributors
 * Michael Wilson -- Intersphinx HTTP basic auth support
 * Nathan Damon -- bugfix in validation of static paths in html builders
 * Pauli Virtanen -- autodoc improvements, autosummary extension
+* A. Rafey Khan -- improved intersphinx typing
 * Rob Ruana -- napoleon extension
 * Robert Lehmann -- gettext builder (GSOC project)
 * Roland Meister -- epub builder

CHANGES.rst

@@ -17,6 +17,7 @@ Incompatible changes
   Code-blokcs are unchanged as FreeMono is now loaded with ``Scale=0.9``.
   An adjustement to existing projects is needed only if they used a custom
   :ref:`fontpkg` configuration and did not set :ref:`fvset`.
+* #12875: Disable smartquotes for languages: ``zh_CN`` and ``zh_TW`` by default.
 
 Deprecated
 ----------
@@ -48,6 +49,19 @@ Features added
 * #12743: Add :option:`sphinx-build --exception-on-warning`,
   to raise an exception when warnings are emitted during the build.
   Patch by Adam Turner and Jeremy Maitin-Shepard.
+* #12907: Add :confval:`html_last_updated_use_utc` to allow using
+  universal time (GMT/UTC) instead of local time for the date-time
+  supplied to :confval:`html_last_updated_fmt`.
+  Patch by Adam Turner.
+* #12910: Copyright entries now support the ``'%Y'`` placeholder
+  to substitute the current year.
+  This is helpful for reducing the reliance on Python modules
+  such as :py:mod:`time` or :py:mod:`datetime` in :file:`conf.py`.
+  See :ref:`the docs <config-copyright>` for further detail.
+  Patch by Adam Turner.
+* #11781: Add roles for referencing CVEs (:rst:role:`:cve: <cve>`)
+  and CWEs (:rst:role:`:cwe: <cwe>`).
+  Patch by Hugo van Kemenade.
 
 Bugs fixed
 ----------
@@ -96,6 +110,19 @@ Bugs fixed
   file URL (user-defined base URL of an intersphinx project are left untouched
   even if they end with double forward slashes).
   Patch by Bénédikt Tran.
+* #12796: Enable parallel reading if requested,
+  even if there are fewer than 6 documents.
+  Patch by Matthias Geier.
+* #12844: Restore support for ``:noindex:`` for the :rst:dir:`js:module`
+  and :rst:dir:`py:module` directives.
+  Patch by Stephen Finucane.
+* #12916: Restore support for custom templates named with the legacy ``_t``
+  suffix during ``apidoc`` RST rendering (regression in 7.4.0).
+  Patch by James Addison.
+* #12451: Only substitute copyright notice years with values from
+  ``SOURCE_DATE_EPOCH`` for entries that match the current system clock year,
+  and disallow substitution of future years.
+  Patch by James Addison and Adam Turner.
 
 Testing
 -------

EXAMPLES.rst

@@ -329,6 +329,7 @@ Documentation using pydata_sphinx_theme
 * `NetworkX <https://networkx.org/documentation/stable/>`__
 * `Numpy <https://numpy.org/doc/stable/>`__
 * `Pandas <https://pandas.pydata.org/docs/>`__
+* `PhaseFieldX <https://phasefieldx.readthedocs.io/>`__
 * `Pystra (continuation of PyRe) <https://pystra.github.io/pystra/>`__
 * `PyVista <https://docs.pyvista.org/>`__
 * `SciPy <https://docs.scipy.org/doc/scipy/>`__

LICENSE.rst

@@ -29,39 +29,3 @@ DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
 THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-
-
-Licenses for incorporated software
-==================================
-
-The included implementation of NumpyDocstring._parse_numpydoc_see_also_section
-was derived from code under the following license:
-
--------------------------------------------------------------------------------
-
-Copyright (C) 2008 Stefan van der Walt <stefan@mentat.za.net>, Pauli Virtanen <pav@iki.fi>
-
-Redistribution and use in source and binary forms, with or without
-modification, are permitted provided that the following conditions are
-met:
-
- 1. Redistributions of source code must retain the above copyright
-    notice, this list of conditions and the following disclaimer.
- 2. Redistributions in binary form must reproduce the above copyright
-    notice, this list of conditions and the following disclaimer in
-    the documentation and/or other materials provided with the
-    distribution.
-
-THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
-IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
-WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
-DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
-INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
-(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
-SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
-HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
-STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
-IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
-POSSIBILITY OF SUCH DAMAGE.
-
--------------------------------------------------------------------------------

doc/_themes/sphinx13/static/sphinx13.css

@@ -321,6 +321,13 @@ cite, code, tt {
     letter-spacing: -0.02em;
 }
 
+div.body code.literal {
+    background-color: #f3f4f5;
+    border: 1px solid #d1d5da;
+    border-radius: 0.25rem;
+    padding: .1rem .2rem;
+}
+
 table.deprecated code.literal {
     word-break: break-all;
 }
@@ -702,17 +709,19 @@ ul.search {
 }
 ul.search li {
     padding: 5px 0 5px 10px;
-    list-style-type: "\25A1";  /* Unicode: White Square */
 }
-ul.search li.context-index {
+
+/* note: these rules apply to search results from the built-in Sphinx HTML/JS search engine
+   and only take effect in dev builds. The released docs use the ReadTheDocs search engine and are not affected. */
+ul.search li.kind-index {
     list-style-type: "\1F4D1";  /* Unicode: Bookmark Tabs */
 }
-ul.search li.context-object {
+ul.search li.kind-object {
     list-style-type: "\1F4E6";  /* Unicode: Package */
 }
-ul.search li.context-title {
+ul.search li.kind-title {
     list-style-type: "\1F4C4";  /* Unicode: Page Facing Up */
 }
-ul.search li.context-text {
+ul.search li.kind-text {
     list-style-type: "\1F4C4";  /* Unicode: Page Facing Up */
 }

doc/changes/1.8.rst

@@ -147,7 +147,7 @@ Bugs fixed
 ----------
 
 * #5418: Incorrect default path for sphinx-build -d/doctrees files
-* #5421: autodoc emits deprecation warning for :confval:`autodoc_default_flags`
+* #5421: autodoc emits deprecation warning for :confval:`!autodoc_default_flags`
 * #5422: lambda object causes PicklingError on storing environment
 * #5417: Sphinx fails to build with syntax error in Python 2.7.5
 * #4911: add latexpdf to make.bat for non make-mode
@@ -251,7 +251,7 @@ Deprecated
 1.8.0b1
 
 * :confval:`!source_parsers` is deprecated
-* :confval:`autodoc_default_flags` is deprecated
+* :confval:`!autodoc_default_flags` is deprecated
 * quickstart: ``--epub`` option becomes default, so it is deprecated
 * Drop function based directive support.  For now, Sphinx only supports class
   based directives (see :class:`~docutils.parsers.rst.Directive`)

doc/changes/3.5.rst

@@ -108,7 +108,7 @@ Features added
   functions in source code and keep them not evaluated for readability.
 * #8619: html: kbd role generates customizable HTML tags for compound keys
 * #8634: html: Allow to change the order of JS/CSS via ``priority`` parameter
-  for :meth:`.Sphinx.add_js_file()` and :meth:`.Sphinx.add_css_file()`
+  for :meth:`.Sphinx.add_js_file` and :meth:`.Sphinx.add_css_file`
 * #6241: html: Allow to add JS/CSS files to the specific page when an extension
   calls ``app.add_js_file()`` or ``app.add_css_file()`` on
   :event:`html-page-context` event

doc/changes/4.4.rst

@@ -27,7 +27,7 @@ Features added
   by an extlink, suggesting a replacement.
 * #9961: html: Support nested <kbd> HTML elements in other HTML builders
 * #10013: html: Allow to change the loading method of JS via ``loading_method``
-  parameter for :meth:`.Sphinx.add_js_file()`
+  parameter for :meth:`.Sphinx.add_js_file`
 * #9551: html search: "Hide Search Matches" link removes "highlight" parameter
   from URL
 * #9815: html theme: Wrap sidebar components in div to allow customizing their

doc/conf.py

@@ -3,17 +3,9 @@
 
 import os
 import re
-import time
 from typing import TYPE_CHECKING
 
-from sphinx import __display_version__, addnodes
-from sphinx.application import Sphinx
-from sphinx.environment import BuildEnvironment
-
-if TYPE_CHECKING:
-    from pathlib import Path
-
-    from docutils import nodes
+from sphinx import __display_version__
 
 os.environ['SPHINX_AUTODOC_RELOAD_MODULES'] = '1'
 
@@ -34,7 +26,7 @@
 exclude_patterns = ['_build']
 
 project = 'Sphinx'
-copyright = f'2007-{time.strftime("%Y")}, the Sphinx developers'
+copyright = '2007-%Y, the Sphinx developers'
 release = version = __display_version__
 show_authors = True
 nitpicky = True
@@ -194,6 +186,7 @@
     ('js:func', 'number'),
     ('js:func', 'string'),
     ('py:attr', 'srcline'),
+    ('py:class', '_AutodocProcessDocstringListener'),
     ('py:class', '_ConfigRebuild'),  # sphinx.application.Sphinx.add_config_value
     ('py:class', '_StrPath'),  # sphinx.environment.BuildEnvironment.doc2path
     ('py:class', 'Element'),  # sphinx.domains.Domain
@@ -262,10 +255,20 @@
 
 # -- Extension interface -------------------------------------------------------
 
+from sphinx import addnodes  # NoQA: E402
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from docutils.nodes import Element
+
+    from sphinx.application import Sphinx
+    from sphinx.environment import BuildEnvironment
+
 _event_sig_re = re.compile(r'([a-zA-Z-]+)\s*\((.*)\)')
 
 
-def parse_event(_env: BuildEnvironment, sig: str, signode: nodes.Element) -> str:
+def parse_event(_env: BuildEnvironment, sig: str, signode: Element) -> str:
     m = _event_sig_re.match(sig)
     if m is None:
         signode += addnodes.desc_name(sig, sig)
@@ -338,10 +341,8 @@ def build_redirects(app: Sphinx, exception: Exception | None) -> None:
 
 
 def setup(app: Sphinx) -> None:
-    from sphinx.ext.autodoc import cut_lines
     from sphinx.util.docfields import GroupedField
 
-    app.connect('autodoc-process-docstring', cut_lines(4, what=['module']))
     app.connect('include-read', linkify_issues_in_changelog)
     app.connect('build-finished', build_redirects)
     fdesc = GroupedField(