Merge branch '4.x' into 6525_linkcheck_warn_redirects

.github/ISSUE_TEMPLATE/bug-report.yml

@@ -0,0 +1,94 @@
+name: Bug report
+description: Something is not working correctly.
+labels: "bug"
+
+body:
+  - type: textarea
+    attributes:
+      label: Describe the bug
+      description: >-
+        A clear and concise description of what the bug is.
+    validations:
+      required: true
+
+  - type: textarea
+    attributes:
+      label: How to Reproduce
+      description: Please provide steps to reproduce this bug.
+      value: |
+        <Paste your command-line here which cause the problem>
+        ```
+        $ git clone https://github.com/.../some_project
+        $ cd some_project
+        $ pip install -r requirements.txt
+        $ cd docs
+        $ make html SPHINXOPTS="-D language=de"
+        $ # open _build/html/index and see bla bla
+        ```
+    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
+      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
+    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]
+    validations:
+      required: false
+  - type: textarea
+    attributes:
+      label: Additional context
+      description: >-
+        Add any other context about the problem here.
+        [e.g. URL or Ticket]

CHANGES

@@ -37,18 +37,43 @@ 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
+* #9358: html: Add "heading" role to the toctree items
 * #9129: html search: Show search summaries when html_copy_source = False
+* #9307: html search: Prevent corrections and completions in search field
 * #9120: html theme: Eliminate prompt characters of code-block from copyable
   text
 * #9176: i18n: Emit a debug message if message catalog file not found under
   :confval:`locale_dirs`
+* #9016: linkcheck: Support checking anchors on github.com
+* #9016: linkcheck: Add a new event :event:`linkcheck-process-uri` to modify
+  URIs before checking hyperlinks
 * #6525: linkcheck: Add :confval:`linkcheck_allowed_redirects` to mark
   hyperlinks that are redirected to expected URLs as "working"
 * #1874: py domain: Support union types using ``|`` in info-field-list
+* #9268: py domain: :confval:`python_use_unqualified_type_names` supports type
+  field in info-field-list
 * #9097: Optimize the paralell build
 * #9131: Add :confval:`nitpick_ignore_regex` to ignore nitpicky warnings using
   regular expressions
+* #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.
+* #9166: LaTeX: support containers in LaTeX output
 
 
 Bugs fixed
@@ -59,17 +84,30 @@ Bugs fixed
   undocumented
 * #9185: autodoc: typehints for overloaded functions and methods are inaccurate
 * #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
+* #9319: quickstart: Make sphinx-quickstart exit when conf.py already exists
+* #9387: xml: XML Builder ignores custom visitors
 * #9224: ``:param:`` and ``:type:`` fields does not support a type containing
   whitespace (ex. ``Dict[str, str]``)
+* #8945: when transforming typed fields, call the specified role instead of
+  making an single xref. For C and C++, use the ``expr`` role for typed fields.
 
 Testing
 --------
 
-Release 4.0.3 (in development)
+Release 4.0.4 (in development)
 ==============================
 
 Dependencies
@@ -90,6 +128,30 @@ Bugs fixed
 Testing
 --------
 
+Release 4.0.3 (released Jul 05, 2021)
+=====================================
+
+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
+----------
+
+* #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
+
 Release 4.0.2 (released May 20, 2021)
 =====================================
 

EXAMPLES

@@ -170,6 +170,7 @@ Documentation using sphinx_rtd_theme
 * `Arcade <https://arcade.academy/>`__
 * `aria2 <https://aria2.github.io/manual/en/html/>`__
 * `ASE <https://wiki.fysik.dtu.dk/ase/>`__
+* `asvin <https://asvin.readthedocs.io/>`__
 * `Autofac <https://docs.autofac.org/>`__
 * `BigchainDB <https://docs.bigchaindb.com/>`__
 * `Blender Reference Manual <https://docs.blender.org/manual/>`__

doc/_templates/index.html

@@ -33,7 +33,7 @@ <h1>{{ _('Welcome') }}</h1>
     <li>{%trans path=pathto('ext/builtins')%}<b>Extensions:</b> automatic testing of code snippets, inclusion of
       docstrings from Python modules (API docs), and
       <a href="{{ path }}#builtin-sphinx-extensions">more</a>{%endtrans%}</li>
-    <li>{%trans path=pathto("usage/extensions")%}<b>Contributed extensions:</b> dozens of
+    <li>{%trans path=pathto("usage/extensions/index")%}<b>Contributed extensions:</b> dozens of
       extensions <a href="{{ path }}#third-party-extensions">contributed by users</a>;
       most of them installable from PyPI{%endtrans%}</li>
   </ul>
@@ -52,23 +52,25 @@ <h2 style="margin-bottom: 0">{%trans%}Documentation{%endtrans%}</h2>
         <p class="biglink"><a class="biglink" href="{{ pathto("usage/quickstart") }}">{%trans%}First steps with Sphinx{%endtrans%}</a><br/>
            <span class="linkdescr">{%trans%}overview of basic tasks{%endtrans%}</span></p>
       </td><td>
-        {%- if hasdoc('search') %}<p class="biglink"><a class="biglink" href="{{ pathto("search") }}">{%trans%}Search page{%endtrans%}</a><br/>
-           <span class="linkdescr">{%trans%}search the documentation{%endtrans%}</span></p>{%- endif %}
+        <p class="biglink"><a class="biglink" href="{{ pathto("tutorial/index") }}">{%trans%}Tutorial{%endtrans%}</a><br/>
+           <span class="linkdescr">{%trans%}beginners tutorial{%endtrans%}</span></p>
       </td>
     </tr><tr>
       <td>
         <p class="biglink"><a class="biglink" href="{{ pathto("contents") }}">{%trans%}Contents{%endtrans%}</a><br/>
            <span class="linkdescr">{%trans%}for a complete overview{%endtrans%}</span></p>
       </td><td>
-        {%- if hasdoc('genindex') %}<p class="biglink"><a class="biglink" href="{{ pathto("genindex") }}">{%trans%}General Index{%endtrans%}</a><br/>
-           <span class="linkdescr">{%trans%}all functions, classes, terms{%endtrans%}</span></p>{%- endif %}
+        {%- if hasdoc('search') %}<p class="biglink"><a class="biglink" href="{{ pathto("search") }}">{%trans%}Search page{%endtrans%}</a><br/>
+           <span class="linkdescr">{%trans%}search the documentation{%endtrans%}</span></p>{%- endif %}
       </td>
     </tr><tr>
       <td>
         <p class="biglink"><a class="biglink" href="{{ pathto("changes") }}">{%trans%}Changes{%endtrans%}</a><br/>
            <span class="linkdescr">{%trans%}release history{%endtrans%}</span></p>
       </td><td>
-      </td>
+        {%- if hasdoc('genindex') %}<p class="biglink"><a class="biglink" href="{{ pathto("genindex") }}">{%trans%}General Index{%endtrans%}</a><br/>
+           <span class="linkdescr">{%trans%}all functions, classes, terms{%endtrans%}</span></p>{%- endif %}
+      </td><td>
     </tr>
   </table>
 

doc/contents.rst

@@ -7,6 +7,7 @@ Sphinx documentation contents
    :maxdepth: 2
 
    usage/index
+   tutorial/index
    development/index
    man/index
 

doc/development/theming.rst

@@ -207,9 +207,9 @@ inside your module:
 First, define the registration function, which accepts the arguments for
 :event:`html-page-context`.
 
-Within the registration function, define the template function that you'd like to use
-within Jinja. The template function should return a string or Python objects (lists,
-dictionaries) with strings inside that Jinja uses in the templating process
+Within the registration function, define the template function that you'd like to
+use within Jinja. The template function should return a string or Python objects
+(lists, dictionaries) with strings inside that Jinja uses in the templating process
 
 .. note::
 
@@ -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/appapi.rst

@@ -159,7 +159,9 @@ connect handlers to the events.  Example:
 
 Below is an overview of each event that happens during a build. In the list
 below, we include the event name, its callback parameters, and the input and output
-type for that event::
+type for that event:
+
+.. code-block:: none
 
    1. event.config-inited(app,config)
    2. event.builder-inited(app)
@@ -168,18 +170,18 @@ type for that event::
 
    for docname in docnames:
       5. event.env-purge-doc(app, env, docname)
-      
+
       if doc changed and not removed:
          6. source-read(app, docname, source)
          7. run source parsers: text -> docutils.document
             - parsers can be added with the app.add_source_parser() API
          8. apply transforms based on priority: docutils.document -> docutils.document
             - event.doctree-read(app, doctree) is called in the middle of transforms,
               transforms come before/after this event depending on their priority.
-   
+
    9. event.env-merge-info(app, env, docnames, other)
       - if running in parallel mode, this event will be emitted for each process
-   
+
    10. event.env-updated(app, env)
    11. event.env-get-updated(app, env)
    12. event.env-check-consistency(app, env)
@@ -377,13 +379,22 @@ Here is a more detailed list of these events.
    ``'page.html'`` as the HTML template for this page.
 
    .. note:: You can install JS/CSS files for the specific page via
-             :meth:`Sphinx.add_js_file` and :meth:`Sphinx.add_css_file` since v3.5.0.
+             :meth:`Sphinx.add_js_file` and :meth:`Sphinx.add_css_file` since
+             v3.5.0.
 
    .. versionadded:: 0.4
 
    .. versionchanged:: 1.3
       The return value can now specify a template name.
 
+.. event:: linkcheck-process-uri (app, uri)
+
+   Emitted when the linkcheck builder collects hyperlinks from document.  *uri*
+   is a collected URI.  The event handlers can modify the URI by returning a
+   string.
+
+   .. versionadded:: 4.1
+
 .. event:: build-finished (app, exception)
 
    Emitted when a build has finished, before Sphinx exits, usually used for