Merge branch '4.x' into humitos/add-html-assets-in-all-pages

CHANGES

@@ -37,6 +37,8 @@ Features added
 * #3014: autodoc: Add :event:`autodoc-process-bases` to modify the base classes
   of the class definitions
 * #9272: autodoc: Render enum values for the default argument value better
+* #9384: autodoc: ``autodoc_typehints='none'`` now erases typehints for
+  variables, attributes and properties
 * #3257: autosummary: Support instance attributes for classes
 * #9129: html search: Show search summaries when html_copy_source = False
 * #9307: html search: Prevent corrections and completions in search field
@@ -56,6 +58,18 @@ Features added
 * #9174: Add ``Sphinx.set_html_assets_policy`` to tell extensions to include
   HTML assets in all the pages. Extensions can check this via
   ``Sphinx.registry.html_assets_policy``
+* C++, add support for
+
+  - ``inline`` variables,
+  - ``consteval`` functions,
+  - ``constinit`` variables,
+  - ``char8_t``,
+  - ``explicit(<constant expression>)`` specifier,
+  - digit separators in literals, and
+  - constraints in placeholder type specifiers, aka. adjective syntax
+    (e.g., ``Sortable auto &v``).
+
+* C, add support for digit separators in literals.
 
 
 Bugs fixed
@@ -68,10 +82,14 @@ Bugs fixed
 * #9250: autodoc: The inherited method not having docstring is wrongly parsed
 * #9283: autodoc: autoattribute directive failed to generate document for an
   attribute not having any comment
+* #9364: autodoc: single element tuple on the default argument value is wrongly
+  rendered
 * #9317: html: Pushing left key causes visiting the next page at the first page
+* #9381: html: URL for html_favicon and html_log does not work
 * #9270: html theme : pyramid theme generates incorrect logo links
 * #9217: manpage: The name of manpage directory that is generated by
   :confval:`man_make_section_directory` is not correct
+* #9350: manpage: Fix font isn't reset after keyword at the top of samp role
 * #9306: Linkcheck reports broken link when remote server closes the connection
   on HEAD request
 * #9280: py domain: "exceptions" module is not displayed
@@ -98,10 +116,23 @@ Deprecated
 Features added
 --------------
 
+* C, add C23 keywords ``_Decimal32``, ``_Decimal64``, and ``_Decimal128``.
+* #9354: C, add :confval:`c_extra_keywords` to allow user-defined keywords
+  during parsing.
+* Revert the removal of ``sphinx.util:force_decode()`` to become some 3rd party
+  extensions available again during 5.0
+
 Bugs fixed
 ----------
 
-* 9313: LaTeX: complex table with merged cells broken since 4.0
+* #9330: changeset domain: :rst:dir:`versionchanged` with contents being a list
+  will cause error during pdf build
+* #9313: LaTeX: complex table with merged cells broken since 4.0
+* #9305: LaTeX: backslash may cause Improper discretionary list pdf build error
+  with Japanese engines
+* #9354: C, remove special macro names from the keyword list.
+  See also :confval:`c_extra_keywords`.
+* #9322: KeyError is raised on PropagateDescDomain transform
 
 Testing
 --------

doc/development/theming.rst

@@ -256,6 +256,9 @@ Here is some sample code to accomplish this:
 
 .. code-block:: python
 
+   from os import path
+   from sphinx.util.fileutil import copy_asset_file
+
    def copy_custom_files(app, exc):
        if app.builder.format == 'html' and not exc:
            staticdir = path.join(app.builder.outdir, '_static')

doc/extdev/deprecated.rst

@@ -750,8 +750,9 @@ The following is a list of deprecated interfaces.
 
    * - ``sphinx.environment.NoUri``
      - 2.1
-     - 4.0
+     - 3.0
      - ``sphinx.errors.NoUri``
+
    * - ``sphinx.ext.apidoc.format_directive()``
      - 2.1
      - 4.0
@@ -1035,7 +1036,7 @@ The following is a list of deprecated interfaces.
 
    * - ``sphinx.util.force_decode()``
      - 2.0
-     - 4.0
+     - 5.0
      - N/A
 
    * - ``sphinx.util.get_matching_docs()``

doc/latex.rst

@@ -282,7 +282,29 @@ Keys that don't need to be overridden unless in special cases are:
    "inputenc" package inclusion.
 
    Default: ``'\\usepackage[utf8]{inputenc}'`` when using pdflatex, else
-   ``''``
+   ``''``.
+
+   .. note::
+
+      If using ``utf8x`` in place of ``utf8`` it is mandatory to extend the
+      LaTeX preamble with suitable ``\PreloadUnicodePage{<number>}`` commands,
+      as per the ``utf8x`` documentation (``texdoc ucs`` on a TeXLive based
+      TeX installation).  Else, unexpected and possibly hard-to-spot problems
+      (i.e. not causing a build crash) may arise in the PDF, in particular
+      regarding hyperlinks.
+
+      Even if these precautions are taken, PDF build via ``pdflatex`` engine
+      may crash due to upstream LaTeX not being fully compatible with
+      ``utf8x``.  For example, in certain circumstances related to
+      code-blocks, or attempting to include images whose filenames contain
+      Unicode characters.  Indeed, starting in 2015, upstream LaTeX with
+      ``pdflatex`` engine has somewhat enhanced native support for Unicode and
+      is becoming more and more incompatible with ``utf8x``.  In particular,
+      since the October 2019 LaTeX release, filenames can use Unicode
+      characters, and even spaces.  At Sphinx level this means e.g. that the
+      :dudir:`image` and :dudir:`figure` directives are now compatible with
+      such filenames for PDF via LaTeX output.  But this is broken if
+      ``utf8x`` is in use.
 
    .. versionchanged:: 1.4.3
       Previously ``'\\usepackage[utf8]{inputenc}'`` was used for all

doc/tutorial/index.rst

@@ -41,7 +41,7 @@ content.
    Lumache
    =======
 
-   **Lumache** (/luˈmake/) is a Python library for cooks and food lovers that
+   **Lumache** (/lu'make/) is a Python library for cooks and food lovers that
    creates recipes mixing random ingredients.
 
 It is a good moment to create a Python virtual environment and install the
@@ -84,40 +84,46 @@ directory and configuration layout for your project inside the ``docs`` folder.
 To proceed, answer each question as follows:
 
 - ``> Separate source and build directories (y/n) [n]``: Write "``y``" (without
-  quotes) and press :kbd:`Enter`.  - ``> Project name``: Write "``Lumache``"
-  (without quotes) and press :kbd:`Enter`.  - ``> Author name(s)``: Write
-  "``Graziella``" (without quotes) and press :kbd:`Enter`.  - ``> Project
-  release []``: Write "``0.1``" (without quotes) and press :kbd:`Enter`.  - ``>
-  Project language [en]``: Leave it empty (the default, English) and press
+  quotes) and press :kbd:`Enter`.
+- ``> Project name``: Write "``Lumache``" (without quotes) and press
+  :kbd:`Enter`.
+- ``> Author name(s)``: Write "``Graziella``" (without quotes) and press
+  :kbd:`Enter`.
+- ``> Project release []``: Write "``0.1``" (without quotes) and press
+  :kbd:`Enter`.
+- ``> Project language [en]``: Leave it empty (the default, English) and press
   :kbd:`Enter`.
 
 After the last question, you will see the new ``docs`` directory with the
 following content.
 
 .. code-block:: text
 
-    docs ├── build ├── make.bat ├── Makefile └── source ├── conf.py ├──
-    index.rst ├── _static └── _templates
+   docs
+   ├── build
+   ├── make.bat
+   ├── Makefile
+   └── source
+      ├── conf.py
+      ├── index.rst
+      ├── _static
+      └── _templates
 
 The purpose of each of these files is:
 
 ``build/``
-
   An empty directory (for now) that will hold the rendered documentation.
 
 ``make.bat`` and ``Makefile``
-
   Convenience scripts to simplify some common Sphinx operations, such as
   rendering the content.
 
 ``source/conf.py``
-
   A Python script holding the configuration of the Sphinx project.  It contains
   the project name and release you specified to ``sphinx-quickstart``, as well
   as some extra configuration keys.
 
 ``source/index.rst``
-
   The :term:`master document` of the project, which serves as welcome page and
   contains the root of the "table of contents tree" (or *toctree*).
 
@@ -149,7 +155,7 @@ Modify the file as follows:
    Welcome to Lumache's documentation!
    ===================================
 
-   **Lumache** (/luˈmake/) is a Python library for cooks and food lovers that
+   **Lumache** (/lu'make/) is a Python library for cooks and food lovers that
    creates recipes mixing random ingredients.  It pulls data from the `Open Food
    Facts database <https://world.openfoodfacts.org/>`_ and offers a *simple* and
    *intuitive* API.
@@ -160,10 +166,11 @@ Modify the file as follows:
 
 This showcases several features of the reStructuredText syntax, including:
 
-- a **section header** using ``===`` for the underline, - two examples of
-  :ref:`rst-inline-markup`: ``**strong emphasis**`` (typically bold) and
-  ``*emphasis*`` (typically italics), - an **inline external link**, - and a
-  ``note`` **admonition** (one of the available :ref:`directives
+- a **section header** using ``===`` for the underline,
+- two examples of :ref:`rst-inline-markup`: ``**strong emphasis**`` (typically
+  bold) and ``*emphasis*`` (typically italics),
+- an **inline external link**,
+- and a ``note`` **admonition** (one of the available :ref:`directives
   <rst-directives>`)
 
 Now to render it with the new content, you can use the ``sphinx-build`` command

doc/usage/configuration.rst

@@ -2689,6 +2689,14 @@ Options for the C domain
 
    .. versionadded:: 3.0
 
+.. confval:: c_extra_keywords
+
+  A list of identifiers to be recognized as keywords by the C parser.
+  It defaults to ``['alignas', 'alignof', 'bool', 'complex', 'imaginary',
+  'noreturn', 'static_assert', 'thread_local']``.
+
+  .. versionadded:: 4.0.3
+
 .. confval:: c_allow_pre_v3
 
    A boolean (default ``False``) controlling whether to parse and try to

doc/usage/extensions/napoleon.rst

@@ -325,9 +325,9 @@ sure that "sphinx.ext.napoleon" is enabled in `conf.py`::
    **If True**::
 
        def __init__(self):
-           \"\"\"
+           """
            This will be included in the docs because it has a docstring
-           \"\"\"
+           """
 
        def __init__(self):
            # This will NOT be included in the docs
@@ -509,7 +509,7 @@ sure that "sphinx.ext.napoleon" is enabled in `conf.py`::
 .. confval:: napoleon_preprocess_types
 
    True to convert the type definitions in the docstrings as references.
-   Defaults to *True*.
+   Defaults to *False*.
 
    .. versionadded:: 3.2.1
    .. versionchanged:: 3.5

sphinx/builders/html/__init__.py

@@ -468,9 +468,6 @@ def prepare_writing(self, docnames: Set[str]) -> None:
         else:
             self.last_updated = None
 
-        logo = path.basename(self.config.html_logo) if self.config.html_logo else ''
-        favicon = path.basename(self.config.html_favicon) if self.config.html_favicon else ''
-
         self.relations = self.env.collect_relations()
 
         rellinks: List[Tuple[str, str, str, str]] = []
@@ -513,8 +510,8 @@ def prepare_writing(self, docnames: Set[str]) -> None:
             'rellinks': rellinks,
             'builder': self.name,
             'parents': [],
-            'logo': logo,
-            'favicon': favicon,
+            'logo': self.config.html_logo or '',
+            'favicon': self.config.html_favicon or '',
             'html5_doctype': html5_ready and not self.config.html4_writer,
         }
         if self.theme:

sphinx/domains/c.py

@@ -55,10 +55,15 @@
     'else', 'enum', 'extern', 'float', 'for', 'goto', 'if', 'inline', 'int', 'long',
     'register', 'restrict', 'return', 'short', 'signed', 'sizeof', 'static', 'struct',
     'switch', 'typedef', 'union', 'unsigned', 'void', 'volatile', 'while',
-    '_Alignas', 'alignas', '_Alignof', 'alignof', '_Atomic', '_Bool', 'bool',
-    '_Complex', 'complex', '_Generic', '_Imaginary', 'imaginary',
-    '_Noreturn', 'noreturn', '_Static_assert', 'static_assert',
-    '_Thread_local', 'thread_local',
+    '_Alignas', '_Alignof', '_Atomic', '_Bool', '_Complex',
+    '_Decimal32', '_Decimal64', '_Decimal128',
+    '_Generic', '_Imaginary', '_Noreturn', '_Static_assert', '_Thread_local',
+]
+# These are only keyword'y when the corresponding headers are included.
+# They are used as default value for c_extra_keywords.
+_macroKeywords = [
+    'alignas', 'alignof', 'bool', 'complex', 'imaginary', 'noreturn', 'static_assert',
+    'thread_local',
 ]
 
 # these are ordered by preceedence
@@ -2536,6 +2541,12 @@ def _parse_nested_name(self) -> ASTNestedName:
             if identifier in _keywords:
                 self.fail("Expected identifier in nested name, "
                           "got keyword: %s" % identifier)
+            if self.matched_text in self.config.c_extra_keywords:
+                msg = "Expected identifier, got user-defined keyword: %s." \
+                      + " Remove it from c_extra_keywords to allow it as identifier.\n" \
+                      + "Currently c_extra_keywords is %s."
+                self.fail(msg % (self.matched_text,
+                                 str(self.config.c_extra_keywords)))
             ident = ASTIdentifier(identifier)
             names.append(ident)
 
@@ -2712,6 +2723,12 @@ def _parse_declarator_name_suffix(
                 if self.matched_text in _keywords:
                     self.fail("Expected identifier, "
                               "got keyword: %s" % self.matched_text)
+                if self.matched_text in self.config.c_extra_keywords:
+                    msg = "Expected identifier, got user-defined keyword: %s." \
+                          + " Remove it from c_extra_keywords to allow it as identifier.\n" \
+                          + "Currently c_extra_keywords is %s."
+                    self.fail(msg % (self.matched_text,
+                                     str(self.config.c_extra_keywords)))
                 identifier = ASTIdentifier(self.matched_text)
                 declId = ASTNestedName([identifier], rooted=False)
             else:
@@ -3878,6 +3895,7 @@ def setup(app: Sphinx) -> Dict[str, Any]:
     app.add_domain(CDomain)
     app.add_config_value("c_id_attributes", [], 'env')
     app.add_config_value("c_paren_attributes", [], 'env')
+    app.add_config_value("c_extra_keywords", _macroKeywords, 'env')
     app.add_post_transform(AliasTransform)
 
     app.add_config_value("c_allow_pre_v3", False, 'env')

sphinx/domains/changeset.py

@@ -74,8 +74,10 @@ def run(self) -> List[Node]:
         if self.content:
             self.state.nested_parse(self.content, self.content_offset, node)
         classes = ['versionmodified', versionlabel_classes[self.name]]
-        if len(node):
-            if isinstance(node[0], nodes.paragraph) and node[0].rawsource:
+        if len(node) > 0 and isinstance(node[0], nodes.paragraph):
+            # the contents start with a paragraph
+            if node[0].rawsource:
+                # make the first paragraph translatable
                 content = nodes.inline(node[0].rawsource, translatable=True)
                 content.source = node[0].source
                 content.line = node[0].line
@@ -84,10 +86,16 @@ def run(self) -> List[Node]:
 
             para = cast(nodes.paragraph, node[0])
             para.insert(0, nodes.inline('', '%s: ' % text, classes=classes))
+        elif len(node) > 0:
+            # the contents do not starts with a paragraph
+            para = nodes.paragraph('', '',
+                                   nodes.inline('', '%s: ' % text, classes=classes),
+                                   translatable=False)
+            node.insert(0, para)
         else:
+            # the contents are empty
             para = nodes.paragraph('', '',
-                                   nodes.inline('', '%s.' % text,
-                                                classes=classes),
+                                   nodes.inline('', '%s.' % text, classes=classes),
                                    translatable=False)
             node.append(para)