Merge branch 'master' into builder-api-cleanup

CHANGES.rst

@@ -1,3 +1,17 @@
+Release 8.1.1 (in development)
+==============================
+
+Bugs fixed
+----------
+
+* #13006: Use the preferred https://www.cve.org/ URL for
+  the :rst:role:`:cve: <cve>` role.
+  Patch by Hugo van Kemenade.
+* #13007: LaTeX: Improve resiliency when the required
+  ``fontawesome`` or ``fontawesome5`` packages are not installed.
+  Patch by Jean-François B.
+
+
 Release 8.1.0 (released Oct 10, 2024)
 =====================================
 

doc/_static/diagrams/sphinx_build_flow.dot

@@ -13,26 +13,54 @@ digraph build {
         shape=record
         label = "Sphinx | <init> __init__ | <build> build"
     ];
+    "legend" [
+        shape=record
+        label = <<table border="0" cellborder="0" cellspacing="0">
+            <tr><td align="center"><u><b>Method types</b></u></td></tr>
+            <tr><td align="left"><font color="darkorange">Final</font></td></tr>
+            <tr><td align="left"><font color="darkblue">Overridable</font></td></tr>
+            <tr><td align="left"><font color="darkgreen">Abstract</font></td></tr>
+        </table>>
+    ];
+    {rank=same; "Sphinx" "legend" };
+
+    "Builder.init" [color=darkblue];
+    "Builder.build_all" [color=darkorange];
+    "Builder.build_specific" [color=darkorange];
+    "Builder.build_update" [color=darkorange];
+
     "Sphinx":init -> "Builder.init";
     "Sphinx":build -> "Builder.build_all";
     "Sphinx":build -> "Builder.build_specific";
-    "Builder.build_update" [
-        shape=record
-        label = "<p1> Builder.build_update | Builder.get_outdated_docs"
-    ];
-    "Sphinx":build -> "Builder.build_update":p1 ;
+    "Sphinx":build -> "Builder.build_update";
+
+    "Builder.get_outdated_docs" [color=darkgreen];
+    "Builder.build_update" -> "Builder.get_outdated_docs";
+
+    "Builder.build" [color=darkorange];
 
     "Builder.build_all" -> "Builder.build";
     "Builder.build_specific" -> "Builder.build";
     "Builder.build_update":p1 -> "Builder.build";
 
+    "Builder.read" [color=darkorange];
+    "Builder.write" [color=darkorange];
+    "Builder.finish" [color=darkblue];
+
     "Builder.build" -> "Builder.read";
     "Builder.build" -> "Builder.write";
     "Builder.build" -> "Builder.finish";
 
+    "Builder.read_doc" [color=darkorange];
+    "Builder.write_doctree" [color=darkorange];
+
     "Builder.read" -> "Builder.read_doc";
     "Builder.read_doc" -> "Builder.write_doctree";
 
+    "Builder.prepare_writing" [color=darkblue];
+    "Builder.copy_assets" [color=darkblue];
+    "Builder.write_documents" [color=darkblue];
+
     "Builder.write":p1 -> "Builder.prepare_writing";
     "Builder.write":p1 -> "Builder.copy_assets";
     "Builder.write_documents" [
@@ -41,8 +69,13 @@ digraph build {
     ];
     "Builder.write":p1 -> "Builder.write_documents";
 
+    "Builder.write_doc" [color=darkgreen];
+    "Builder.get_relative_uri" [color=darkblue];
+
     "Builder.write_documents":p1 -> "Builder.write_doc";
     "Builder.write_doc" -> "Builder.get_relative_uri";
 
+    "Builder.get_target_uri" [color=darkgreen];
+
     "Builder.get_relative_uri" -> "Builder.get_target_uri";
 }

doc/extdev/builderapi.rst

@@ -12,7 +12,7 @@ Builder API
    It follows this basic workflow:
 
    .. graphviz:: /_static/diagrams/sphinx_build_flow.dot
-      :caption: UML for the standard Sphinx build workflow
+      :caption: Call graph for the standard Sphinx build workflow
 
    .. rubric:: Overridable Attributes
 

sphinx/__init__.py

@@ -1,6 +1,6 @@
 """The Sphinx documentation toolchain."""
 
-__version__ = '8.1.0'
+__version__ = '8.1.1'
 __display_version__ = __version__  # used for command line version
 
 # Keep this file executable as-is in Python 3!
@@ -30,11 +30,11 @@
 #:
 #: .. versionadded:: 1.2
 #:    Before version 1.2, check the string ``sphinx.__version__``.
-version_info = (8, 1, 0, 'final', 0)
+version_info = (8, 1, 1, 'beta', 0)
 
 package_dir = os.path.abspath(os.path.dirname(__file__))
 
-_in_development = False
+_in_development = True
 if _in_development:
     # Only import subprocess if needed
     import subprocess

sphinx/environment/__init__.py

@@ -54,10 +54,6 @@
     'image_loading': 'link',
     'embed_stylesheet': False,
     'cloak_email_addresses': True,
-    'cve_base_url': 'https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-',
-    'cve_references': None,
-    'cwe_base_url': 'https://cwe.mitre.org/data/definitions/',
-    'cwe_references': None,
     'pep_base_url': 'https://peps.python.org/',
     'pep_references': None,
     'rfc_base_url': 'https://datatracker.ietf.org/doc/html/',

sphinx/roles.py

@@ -17,6 +17,7 @@
 
 if TYPE_CHECKING:
     from collections.abc import Sequence
+    from typing import Final
 
     from docutils.nodes import Element, Node, TextElement, system_message
 
@@ -197,6 +198,8 @@ def process_link(
 
 
 class CVE(ReferenceRole):
+    _BASE_URL: Final = 'https://www.cve.org/CVERecord?id=CVE-'
+
     def run(self) -> tuple[list[Node], list[system_message]]:
         target_id = f'index-{self.env.new_serialno("index")}'
         entries = [
@@ -233,14 +236,15 @@ def run(self) -> tuple[list[Node], list[system_message]]:
         return [index, target, reference], []
 
     def build_uri(self) -> str:
-        base_url = self.inliner.document.settings.cve_base_url
         ret = self.target.split('#', 1)
         if len(ret) == 2:
-            return f'{base_url}{ret[0]}#{ret[1]}'
-        return f'{base_url}{ret[0]}'
+            return f'{CVE._BASE_URL}{ret[0]}#{ret[1]}'
+        return f'{CVE._BASE_URL}{ret[0]}'
 
 
 class CWE(ReferenceRole):
+    _BASE_URL: Final = 'https://cwe.mitre.org/data/definitions/'
+
     def run(self) -> tuple[list[Node], list[system_message]]:
         target_id = f'index-{self.env.new_serialno("index")}'
         entries = [
@@ -277,11 +281,10 @@ def run(self) -> tuple[list[Node], list[system_message]]:
         return [index, target, reference], []
 
     def build_uri(self) -> str:
-        base_url = self.inliner.document.settings.cwe_base_url
         ret = self.target.split('#', 1)
         if len(ret) == 2:
-            return f'{base_url}{int(ret[0])}.html#{ret[1]}'
-        return f'{base_url}{int(ret[0])}.html'
+            return f'{CWE._BASE_URL}{int(ret[0])}.html#{ret[1]}'
+        return f'{CWE._BASE_URL}{int(ret[0])}.html'
 
 
 class PEP(ReferenceRole):

sphinx/texinputs/sphinx.sty

@@ -9,7 +9,7 @@
 % by the Sphinx LaTeX writer.
 
 \NeedsTeXFormat{LaTeX2e}[1995/12/01]
-\ProvidesPackage{sphinx}[2024/07/28 v8.1.0 Sphinx LaTeX package (sphinx-doc)]
+\ProvidesPackage{sphinx}[2024/10/11 v8.1.1 Sphinx LaTeX package (sphinx-doc)]
 
 % provides \ltx@ifundefined
 % (many packages load ltxcmds: graphicx does for pdftex and lualatex but
@@ -885,15 +885,12 @@
   {\DeclareStringOption[fontawesome]{iconpackage}}
   {\DeclareStringOption[none]{iconpackage}}%
 }%
-\newcommand\spx@faIcon[3][]{}%
-% The hacky definition of \spx@faIcon above is to let it by default swallow
-% the icon macro and the \sphinxtitlerowaftericonspacecmd (see
-% \sphinxdotitlerowwithicon in sphinxlatexadmonitions.sty) which inserts
-% a space between it and title.  See how \spx@faIcon is used below.
-%
-% If user sets a title-icon key to some LaTeX code of their own, of course
-% \spx@faIcon is not executed and the inserted space will thus be there, as
-% expected.
+\newcommand\spx@faIcon[2][]{}%
+% The above \spx@faIcon which gobbles one mandatory and one optional
+% argument is put into use only if both fontawesome5 and fontawesome
+% LaTeX packages are not available, as part of the defaults for the
+% div.*_title-icon keys (these keys can be redefined via the sphinxsetup
+% interface).
 %
 \def\spxstring@fontawesome{fontawesome}
 \def\spxstring@fontawesomev{fontawesome5}
@@ -920,8 +917,8 @@
                    \let\faicon@pen\faPencil
               \fi
           % if neither has been required, \spx@faIcon will simply swallow
-          % its argument (and follwing space macro) and it is up to user
-          % to set the keys appropriately.
+          % its argument and it is up to user
+          % to set the various div.*_title-icon keys appropriately.
           \fi\fi %
          }%
          {%

sphinx/texinputs/sphinxlatexadmonitions.sty

@@ -1,7 +1,7 @@
 %% NOTICES AND ADMONITIONS
 %
 % change this info string if making any custom modification
-\ProvidesPackage{sphinxlatexadmonitions}[2024/07/28 v8.1.0 admonitions]
+\ProvidesPackage{sphinxlatexadmonitions}[2024/10/11 v8.1.1 admonitions]
 
 % Provides support for this output mark-up from Sphinx latex writer:
 %
@@ -341,9 +341,11 @@
          \ifdim\wd\z@>\z@
           \textcolor{sphinx#1TtlFgColor}{%
             \@nameuse{sphinx#1TtlIcon}%
-            % This macro is located here and not after the closing brace
-            % for reasons of fall-back \spx@faIcon definition in sphinx.sty
-            % in case fontawesome5 package not found.
+            % The next macro is located here for legacy reasons of earlier
+            % functioning of \spx@faIcon.  When fontawesome{5,}.sty both
+            % are unavailable, it (formerly) gobbled this next macro.
+            % We leave it here now although it could be moved to after
+            % the closing brace.
             \sphinxtitlerowaftericonspacecmd
           }%
          \fi

tests/test_markup/test_markup.py

@@ -166,14 +166,14 @@ def get(name):
             ':cve:`2020-10735`',
             (
                 '<p><span class="target" id="index-0"></span><a class="cve reference external" '
-                'href="https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2020-10735">'
+                'href="https://www.cve.org/CVERecord?id=CVE-2020-10735">'
                 '<strong>CVE 2020-10735</strong></a></p>'
             ),
             (
                 '\\sphinxAtStartPar\n'
                 '\\index{Common Vulnerabilities and Exposures@\\spxentry{Common Vulnerabilities and Exposures}'
                 '!CVE 2020\\sphinxhyphen{}10735@\\spxentry{CVE 2020\\sphinxhyphen{}10735}}'
-                '\\sphinxhref{https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2020-10735}'
+                '\\sphinxhref{https://www.cve.org/CVERecord?id=CVE-2020-10735}'
                 '{\\sphinxstylestrong{CVE 2020\\sphinxhyphen{}10735}}'
             ),
         ),
@@ -183,14 +183,14 @@ def get(name):
             ':cve:`2020-10735#id1`',
             (
                 '<p><span class="target" id="index-0"></span><a class="cve reference external" '
-                'href="https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2020-10735#id1">'
+                'href="https://www.cve.org/CVERecord?id=CVE-2020-10735#id1">'
                 '<strong>CVE 2020-10735#id1</strong></a></p>'
             ),
             (
                 '\\sphinxAtStartPar\n'
                 '\\index{Common Vulnerabilities and Exposures@\\spxentry{Common Vulnerabilities and Exposures}'
                 '!CVE 2020\\sphinxhyphen{}10735\\#id1@\\spxentry{CVE 2020\\sphinxhyphen{}10735\\#id1}}'
-                '\\sphinxhref{https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2020-10735\\#id1}'
+                '\\sphinxhref{https://www.cve.org/CVERecord?id=CVE-2020-10735\\#id1}'
                 '{\\sphinxstylestrong{CVE 2020\\sphinxhyphen{}10735\\#id1}}'
             ),
         ),