Merge branch '5.x'

# Conflicts:
#	.github/workflows/main.yml
#	CHANGES
#	sphinx/__init__.py
#	sphinx/domains/c.py

.github/ISSUE_TEMPLATE/bug-report.yml

@@ -7,16 +7,34 @@ body:
     attributes:
       label: Describe the bug
       description: >-
-        A clear and concise description of what the bug is.
+        A clear and concise description of what the bug is, including the 
+        expected behaviour and what has gone wrong.
+        
+        Please include screenshots, if applicable.
     validations:
       required: true
 
   - type: textarea
     attributes:
       label: How to Reproduce
-      description: Please provide steps to reproduce this bug.
+      description: >-
+        Please provide steps to reproduce this bug, with the smallest possible
+        set of source files. For normal bugs this should ideally be one 
+        ``index.rst`` file, and for ``sphinx.ext.autodoc`` bugs, this should
+        ideally be a single ``index.rst`` file, and a single example Python 
+        module.
       value: |
+        Minimal method (you can also paste the contents of ``index.rst`` and
+        ``conf.py`` into this report):
+        ```bash
+        $ echo "Content demonstrating the bug..." > index.rst
+        $ echo "" > conf.py
+        $ sphinx-build -M html . _build
+        $ # open _build/html/index and see bla bla
         ```
+        
+        ``git clone`` method (this is advised against, to help the Sphinx team):
+        ```bash
         $ git clone https://github.com/.../some_project
         $ cd some_project
         $ pip install -r requirements.txt
@@ -27,67 +45,37 @@ body:
     validations:
       required: true
 
-  - type: textarea
-    attributes:
-      label: Expected behavior
-      description: >-
-        A clear and concise description of what you expected to happen.
-
-  - type: input
-    attributes:
-      label: Your project
-      description: >-
-        Link to your sphinx project, or attach zipped small project sample.
-    validations:
-      required: true
-
-  - type: textarea
-    attributes:
-      label: Screenshots
-      description: >-
-        If applicable, add screenshots to help explain your problem.
-    validations:
-      required: false
-
   - type: markdown
     attributes:
       value: |
         ## Environment info
 
   - type: input
     attributes:
-      label: OS
+      label: Environment Information
       description: >-
-        [e.g. Unix/Linux/Mac/Win/other with version]
-    validations:
-      required: true
-  - type: input
-    attributes:
-      label: Python version
-    validations:
-      required: true
-  - type: input
-    attributes:
-      label: Sphinx version
+        Install development Sphinx 
+        ``pip install https://github.com/AA-Turner/sphinx/archive/refs/heads/5.x.zip``
+        then run ``sphinx-build --bug-report`` or ``python -m sphinx --bug-report``.
+        and paste the output here.
     validations:
       required: true
   - type: input
     attributes:
       label: Sphinx extensions
       description: >-
-        [e.g. sphinx.ext.autodoc, recommonmark]
-    validations:
-      required: false
-  - type: input
-    attributes:
-      label: Extra tools
-      description: >-
-        [e.g. Browser, tex or something else]
+        Attempt to reproduce your error with the smallest set of extensions possible.
+        This makes it easier to determine where the problem you are encountering is.
+        
+        e.g. ["sphinx.ext.autodoc", "recommonmark"]
     validations:
       required: false
   - type: textarea
     attributes:
       label: Additional context
       description: >-
-        Add any other context about the problem here.
-        [e.g. URL or Ticket]
+        Add any other context about the problem here, for example:
+        
+        * Any other tools used (Browser, TeX, etc) with versions
+        * Reference to another issue or pull request
+        * URL to some external resource

.github/workflows/latex.yml

@@ -6,15 +6,16 @@ permissions:
   contents: read
 
 jobs:
-  build:
-    runs-on: ubuntu-18.04
-    name: Python 3.8
+  test:
+    runs-on: ubuntu-latest
+    name: Test on LaTeX image
     container:
-      image: sphinxdoc/docker-ci
+      image: ghcr.io/sphinx-doc/sphinx-ci
     env:
       DO_EPUBCHECK: 1
-      PATH: /python3.8/bin/:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
     steps:
+    - name: Alias python3 to python
+      run: ln -s /usr/bin/python3 /usr/bin/python
     - uses: actions/checkout@v3
     - name: Check Python version
       run: python --version

.github/workflows/main.yml

@@ -7,7 +7,7 @@ permissions:
 
 jobs:
   ubuntu:
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-latest
     name: Python ${{ matrix.python }} (${{ matrix.docutils }})
     strategy:
       fail-fast: false

CHANGES

@@ -49,29 +49,19 @@ Bugs fixed
 Testing
 --------
 
-Release 5.3.0 (in development)
-==============================
-
-Dependencies
-------------
-
-Incompatible changes
---------------------
-
-Deprecated
-----------
-
-Features added
---------------
+Release 5.3.0 (released Oct 16, 2022)
+=====================================
 
-* #10840: One can cross-reference including an option value: ``:option:`--module=foobar```.
+* #10759: LaTeX: add :confval:`latex_table_style` and support the
+  ``'booktabs'``, ``'borderless'``, and ``'colorrows'`` styles.
+  (thanks to Stefan Wiehler for initial pull requests #6666, #6671)
+* #10840: One can cross-reference including an option value like ``:option:`--module=foobar```,
+  ``:option:`--module[=foobar]``` or ``:option:`--module foobar```.
   Patch by Martin Liska.
-
-Bugs fixed
-----------
-
-Testing
---------
+* #10881: autosectionlabel: Record the generated section label to the debug log.
+* #10268: Correctly URI-escape image filenames.
+* #10887: domains: Allow sections in all the content of all object description
+  directives (e.g. :rst:dir:`py:function`). Patch by Adam Turner
 
 Release 5.2.3 (released Sep 30, 2022)
 =====================================

doc/conf.py

@@ -78,14 +78,15 @@
              {\begin{sphinxtheindex}\end{sphinxtheindex}}
 ''',
     'sphinxsetup': """%
-VerbatimColor={RGB}{242,242,242},%
+VerbatimColor=black!5,% tests 5.3.0 extended syntax
 VerbatimBorderColor={RGB}{32,32,32},%
 pre_border-radius=3pt,%
 pre_box-decoration-break=slice,%
 """,
 }
 latex_show_urls = 'footnote'
 latex_use_xindy = True
+latex_table_style = ['booktabs', 'colorrows']
 
 autodoc_member_order = 'groupwise'
 autosummary_generate = False

doc/extdev/deprecated.rst

@@ -10,7 +10,7 @@ major versions (for more details, please see :ref:`deprecation-policy`).
 
 The following is a list of deprecated interfaces.
 
-.. tabularcolumns:: |>{\raggedright}\Y{.4}|>{\centering}\Y{.1}|>{\centering}\Y{.12}|>{\raggedright\arraybackslash}\Y{.38}|
+.. tabularcolumns:: >{\raggedright}\Y{.4}>{\centering}\Y{.1}>{\sphinxcolorblend{!95!red}\centering\noindent\bfseries\color{red}}\Y{.12}>{\raggedright\arraybackslash}\Y{.38}
 
 .. list-table:: deprecated APIs
    :header-rows: 1
@@ -19,7 +19,7 @@ The following is a list of deprecated interfaces.
 
    * - Target
      - Deprecated
-     - (will be) Removed
+     - Removed
      - Alternatives
 
    * - HTML 4 support

doc/latex.rst

@@ -823,16 +823,31 @@ Do not use quotes to enclose values, whether numerical or strings.
        definition of the continuation symbol was changed at 1.5 to accommodate
        various font sizes (e.g. code-blocks can be in footnotes).
 
+.. note::
+
+   Values for colour keys must either:
+
+   - obey the syntax of the ``\definecolor`` LaTeX command, e.g. something
+     such as ``VerbatimColor={rgb}{0.2,0.3,0.5}`` or ``{RGB}{37,23,255}`` or
+     ``{gray}{0.75}`` or (only with package ``xcolor``) ``{HTML}{808080}`` or
+     ...
+
+   - or obey the syntax of the ``\colorlet`` command from package ``xcolor``
+     (which then must exist in the LaTeX installation),
+     e.g. ``VerbatimColor=red!10`` or ``red!50!green`` or ``-red!75`` or
+     ``MyPreviouslyDefinedColour`` or... Refer to xcolor_ documentation for
+     this syntax.
+
+   .. _xcolor: https://ctan.org/pkg/xcolor
+
+   .. versionchanged:: 5.3.0
+      Formerly only the ``\definecolor`` syntax was accepted.
+
 ``TitleColor``
     The colour for titles (as configured via use of package "titlesec".)
 
     Default: ``{rgb}{0.126,0.263,0.361}``
 
-    .. warning::
-
-       Colours set via ``'sphinxsetup'``  must obey the syntax of the
-       argument of the ``color/xcolor`` packages ``\definecolor`` command.
-
 ``InnerLinkColor``
     A colour passed to ``hyperref`` as value of ``linkcolor``  and
     ``citecolor``.
@@ -862,10 +877,47 @@ Do not use quotes to enclose values, whether numerical or strings.
 
     .. versionadded:: 1.6.6
 
-    .. note::
+.. _tablecolors:
+
+``TableRowColorHeader``
+    Sets the background colour for (all) the header rows of tables.
+
+    It will have an effect only if either the :confval:`latex_table_style`
+    contains ``'colorrows'`` or if the table is assigned the ``colorrows``
+    class.  It is ignored for tables with ``nocolorrows`` class.
 
-       Starting with this colour, and for all others following, the
-       names declared to "color" or "xcolor" are prefixed with "sphinx".
+    As for the other ``'sphinxsetup'`` keys, it can also be set or modified
+    from a ``\sphinxsetup{...}`` LaTeX command inserted via the :dudir:`raw`
+    directive, or also from a LaTeX environment associated to a `container
+    class <latexcontainer_>`_ and using such ``\sphinxsetup{...}``.
+
+    Default: ``{gray}{0.86}``
+
+    There is also ``TableMergeColorHeader``.  If used, sets a specific colour
+    for merged single-row cells in the header.
+
+    .. versionadded:: 5.3.0
+
+``TableRowColorOdd``
+    Sets the background colour for odd rows in tables (the row count starts at
+    ``1`` at the first non-header row).  Has an effect only if the
+    :confval:`latex_table_style` contains ``'colorrows'`` or for specific
+    tables assigned the ``colorrows`` class.
+
+    Default: ``{gray}{0.92}``
+
+    There is also ``TableMergeColorOdd``.
+
+    .. versionadded:: 5.3.0
+
+``TableRowColorEven``
+    Sets the background colour for even rows in tables.
+
+    Default ``{gray}{0.98}``
+
+    There is also ``TableMergeColorEven``.
+
+    .. versionadded:: 5.3.0
 
 ``verbatimsep``
     The separation between code lines and the frame.
@@ -1425,6 +1477,8 @@ Miscellany
      Formerly, use of *fncychap* with other styles than ``Bjarne`` was
      dysfunctional.
 
+.. _latexcontainer:
+
 - Docutils :dudir:`container` directives are supported in LaTeX output: to
   let a container class with name ``foo`` influence the final PDF via LaTeX,
   it is only needed to define in the preamble an environment