Merge branch 'master' into latex_xelatex_math

sphinx-doc · Aug 17, 2024 · 6805d44 · 6805d44
2 parents b7983ae + 334e69f
commit 6805d44
Show file tree

Hide file tree

Showing 115 changed files with 2,163 additions and 793 deletions.
diff --git a/.flake8 b/.flake8
@@ -33,5 +33,6 @@ exclude =
     doc/usage/extensions/example*.py,
 per-file-ignores =
     doc/conf.py:W605
+    sphinx/events.py:E704,
     tests/test_extensions/ext_napoleon_pep526_data_google.py:MLL001,
     tests/test_extensions/ext_napoleon_pep526_data_numpy.py:MLL001,
diff --git a/.github/workflows/builddoc.yml b/.github/workflows/builddoc.yml
@@ -14,6 +14,7 @@ concurrency:
 
 env:
   FORCE_COLOR: "1"
+  UV_SYSTEM_PYTHON: "1"  # make uv do global installs
 
 jobs:
   build:
@@ -27,10 +28,14 @@ jobs:
         python-version: "3"
     - name: Install graphviz
       run: sudo apt-get install graphviz
+    - 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: |
-        python -m pip install --upgrade pip
-        python -m pip install .[docs]
+      run: uv pip install .[docs]
     - name: Render the documentation
       run: >
         sphinx-build
@@ -39,4 +44,3 @@ jobs:
         --jobs=auto
         --show-traceback
         --fail-on-warning
-        --keep-going
diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml
@@ -14,6 +14,7 @@ concurrency:
 
 env:
   FORCE_COLOR: "1"
+  UV_SYSTEM_PYTHON: "1"  # make uv do global installs
 
 jobs:
   # If you update any of these commands, don't forget to update the equivalent
@@ -23,17 +24,18 @@ jobs:
 
     steps:
     - uses: actions/checkout@v4
-    - name: Set up Python
-      uses: actions/setup-python@v5
-      with:
-        python-version: "3"
-    - name: Install pip
-      run: python -m pip install --upgrade pip
+    - name: Get Ruff version from pyproject.toml
+      run: |
+        RUFF_VERSION=$(awk -F'[="]' '/\[project\.optional-dependencies\]/ {p=1} /ruff/ {if (p) print $4}' pyproject.toml)
+        echo "RUFF_VERSION=$RUFF_VERSION" >> $GITHUB_ENV
 
     - name: Install Ruff
-      run: |
-          ruff_version=$(awk -F'[="]' '/\[project\.optional-dependencies\]/ {p=1} /ruff/ {if (p) print $4}' pyproject.toml)
-          python -m pip install "ruff==${ruff_version}"
+      run: >
+        curl --no-progress-meter --location --fail
+        --proto '=https' --tlsv1.2
+        --write-out "%{stderr}Downloaded: %{url}\n"
+        "https://astral.sh/ruff/$RUFF_VERSION/install.sh"
+        | sh
 
     - name: Lint with Ruff
       run: ruff check . --output-format github
@@ -50,10 +52,14 @@ jobs:
       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: |
-        python -m pip install --upgrade pip
-        python -m pip install --upgrade "flake8>=6.0"
+      run: uv pip install --upgrade "flake8>=6.0"
     - name: Lint with flake8
       run: flake8 .
 
@@ -66,10 +72,14 @@ jobs:
       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: |
-        python -m pip install --upgrade pip
-        python -m pip install ".[lint,test]"
+      run: uv pip install ".[lint,test]"
     - name: Type check with mypy
       run: mypy
 
@@ -82,10 +92,14 @@ jobs:
       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: |
-        python -m pip install --upgrade pip
-        python -m pip install --upgrade sphinx-lint
+      run: uv pip install --upgrade sphinx-lint
     - name: Lint documentation with sphinx-lint
       run: make doclinter
 
@@ -98,10 +112,14 @@ jobs:
       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: |
-        python -m pip install --upgrade pip
-        python -m pip install --upgrade twine build
+      run: uv pip install --upgrade twine build
     - name: Lint with twine
       run: |
         python -m build .

diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
@@ -36,7 +36,6 @@ jobs:
         - "3.10"
         - "3.11"
         - "3.12"
-        - "3.13-dev"
         docutils:
         - "0.20"
         - "0.21"
@@ -49,12 +48,43 @@ jobs:
     - uses: actions/checkout@v4
     - name: Set up Python ${{ matrix.python }}
       uses: actions/setup-python@v5
-      if: "!endsWith(matrix.python, '-dev')"
       with:
         python-version: ${{ matrix.python }}
+    - name: Check Python version
+      run: python --version --version
+    - name: Install graphviz
+      run: sudo apt-get install graphviz
+    - 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 .[test]
+    - name: Install Docutils ${{ matrix.docutils }}
+      run: uv pip install --upgrade "docutils~=${{ matrix.docutils }}.0"
+    - name: Test with pytest
+      run: python -m pytest -vv --durations 25
+      env:
+        PYTHONWARNINGS: "error"  # treat all warnings as errors
+
+  deadsnakes:
+    runs-on: ubuntu-latest
+    name: Python ${{ matrix.python }} (Docutils ${{ matrix.docutils }})
+    strategy:
+      fail-fast: false
+      matrix:
+        python:
+        - "3.13-dev"
+        docutils:
+        - "0.20"
+        - "0.21"
+
+    steps:
+    - uses: actions/checkout@v4
     - name: Set up Python ${{ matrix.python }} (deadsnakes)
       uses: deadsnakes/[email protected]
-      if: "endsWith(matrix.python, '-dev')"
       with:
         python-version: ${{ matrix.python }}
     - name: Check Python version
@@ -84,10 +114,14 @@ jobs:
         python-version: "3"
     - name: Check Python version
       run: python --version --version
+    - name: Install graphviz
+      run: choco install --no-progress graphviz
+    - name: Install uv
+      run: >
+        Invoke-WebRequest -Uri "https://astral.sh/uv/install.ps1"
+        | Invoke-Expression
     - name: Install dependencies
-      run: |
-        python -m pip install --upgrade pip
-        python -m pip install .[test]
+      run: uv pip install .[test]
     - name: Test with pytest
       run: python -m pytest -vv --durations 25
       env:
@@ -100,9 +134,10 @@ jobs:
     steps:
     - name: Install epubcheck
       run: |
+        EPUBCHECK_VERSION="5.1.0"
         mkdir /tmp/epubcheck && cd /tmp/epubcheck
-        wget https://github.com/w3c/epubcheck/releases/download/v5.1.0/epubcheck-5.1.0.zip
-        unzip epubcheck-5.1.0.zip
+        wget --no-verbose https://github.com/w3c/epubcheck/releases/download/v${EPUBCHECK_VERSION}/epubcheck-${EPUBCHECK_VERSION}.zip
+        unzip epubcheck-${EPUBCHECK_VERSION}.zip
     - uses: actions/checkout@v4
     - name: Set up Python
       uses: actions/setup-python@v5
@@ -112,12 +147,16 @@ jobs:
       run: python --version --version
     - name: Install graphviz
       run: sudo apt-get install graphviz
+    - 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: |
-        python -m pip install --upgrade pip
-        python -m pip install .[test]
+      run: uv pip install .[test]
     - name: Install Docutils' HEAD
-      run: python -m pip install git+https://repo.or.cz/docutils.git\#subdirectory=docutils
+      run: uv pip install "docutils @ git+https://repo.or.cz/docutils.git#subdirectory=docutils"
     - name: Test with pytest
       run: python -m pytest -vv
       env:
@@ -140,13 +179,10 @@ jobs:
     - name: Install graphviz
       run: sudo apt-get install graphviz
     - name: Install uv
-      run: > 
-        curl 
-        --location 
-        --fail
-        --proto '=https' --tlsv1.2 
-        --silent --show-error 
-        https://astral.sh/uv/install.sh
+      run: >
+        curl --no-progress-meter --location --fail
+        --proto '=https' --tlsv1.2
+        "https://astral.sh/uv/install.sh"
         | sh
     - name: Install dependencies
       run: |
@@ -171,10 +207,14 @@ jobs:
         python-version: "3"
     - name: Check Python version
       run: python --version --version
+    - 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: |
-        python -m pip install --upgrade pip
-        python -m pip install .[test]
+      run: uv pip install .[test]
     - name: Test with pytest
       run: python -m pytest -vv --durations 25
       env:
@@ -196,10 +236,14 @@ jobs:
       run: python --version --version
     - name: Install graphviz
       run: sudo apt-get install graphviz
+    - 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: |
-        python -m pip install --upgrade pip
-        python -m pip install .[test] pytest-cov
+      run: uv pip install .[test] pytest-cov
     - name: Test with pytest
       run: python -m pytest -vv --cov . --cov-append --cov-config pyproject.toml
       env:

diff --git a/.github/workflows/nodejs.yml b/.github/workflows/nodejs.yml
@@ -23,11 +23,14 @@ concurrency:
   group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
   cancel-in-progress: true
 
+env:
+  FORCE_COLOR: "1"
+
 jobs:
   build:
     runs-on: ubuntu-latest
     env:
-      node-version: "16"
+      node-version: "20"
 
     steps:
     - uses: actions/checkout@v4
@@ -37,5 +40,4 @@ jobs:
         node-version: ${{ env.node-version }}
         cache: "npm"
     - run: npm install
-    - name: Run headless test
-      run: xvfb-run -a npm test
+    - run: npm test
diff --git a/CHANGES.rst b/CHANGES.rst
@@ -43,6 +43,14 @@ Features added
   output files.
 * #12474: Support type-dependent search result highlighting via CSS.
   Patch by Tim Hoffmann.
+* #12743: No longer exit on the first warning when
+  :option:`--fail-on-warning <sphinx-build --fail-on-warning>` is used.
+  Instead, exit with a non-zero status if any warnings were generated
+  during the build.
+  Patch by Adam Turner.
+* #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.
 
 Bugs fixed
 ----------
@@ -70,6 +78,11 @@ Bugs fixed
   get passed to :program:`latexmk`.  Let :option:`-Q <sphinx-build -Q>`
   (silent) apply as well to the PDF build phase.
   Patch by Jean-François B.
+* #11970, #12551: singlehtml builder: make target URIs to be same-document
+  references in the sense of :rfc:`RFC 3986, §4.4 <3986#section-4.4>`,
+  e.g., ``index.html#foo`` becomes ``#foo``.
+  (note: continuation of a partial fix added in Sphinx 7.3.0)
+  Patch by James Addison (with reference to prior work by Eric Norige)
 
 Testing
 -------

diff --git a/doc/conf.py b/doc/conf.py
@@ -186,19 +186,24 @@
     ('js:func', 'number'),
     ('js:func', 'string'),
     ('py:attr', 'srcline'),
+    ('py:class', '_ConfigRebuild'),  # sphinx.application.Sphinx.add_config_value
     ('py:class', '_StrPath'),  # sphinx.environment.BuildEnvironment.doc2path
     ('py:class', 'Element'),  # sphinx.domains.Domain
     ('py:class', 'Documenter'),  # sphinx.application.Sphinx.add_autodocumenter
     ('py:class', 'IndexEntry'),  # sphinx.domains.IndexEntry
+    ('py:class', 'Lexer'),  # sphinx.application.Sphinx.add_lexer
     ('py:class', 'Node'),  # sphinx.domains.Domain
     ('py:class', 'NullTranslations'),  # gettext.NullTranslations
+    ('py:class', 'Path'),  # sphinx.application.Sphinx.connect
     ('py:class', 'RoleFunction'),  # sphinx.domains.Domain
     ('py:class', 'RSTState'),  # sphinx.utils.parsing.nested_parse_to_nodes
     ('py:class', 'Theme'),  # sphinx.application.TemplateBridge
     ('py:class', 'SearchLanguage'),  # sphinx.application.Sphinx.add_search_language
     ('py:class', 'StringList'),  # sphinx.utils.parsing.nested_parse_to_nodes
     ('py:class', 'system_message'),  # sphinx.utils.docutils.SphinxDirective
     ('py:class', 'TitleGetter'),  # sphinx.domains.Domain
+    ('py:class', 'todo_node'),  # sphinx.application.Sphinx.connect
+    ('py:class', 'Transform'),  # sphinx.application.Sphinx.add_transform
     ('py:class', 'XRefRole'),  # sphinx.domains.Domain
     ('py:class', 'docutils.nodes.Element'),
     ('py:class', 'docutils.nodes.Node'),
@@ -210,6 +215,7 @@
     ('py:class', 'docutils.parsers.rst.states.Inliner'),
     ('py:class', 'docutils.transforms.Transform'),
     ('py:class', 'nodes.NodeVisitor'),
+    ('py:class', 'nodes.TextElement'),  # sphinx.application.Sphinx.connect
     ('py:class', 'nodes.document'),
     ('py:class', 'nodes.reference'),
     ('py:class', 'pygments.lexer.Lexer'),