Merge branch '4.x'

nijel · May 19, 2021 · 1514b03 · 1514b03
2 parents 8350736 + d2d2d7b
commit 1514b03
Show file tree

Hide file tree

Showing 168 changed files with 14,025 additions and 13,156 deletions.
diff --git a/CHANGES b/CHANGES
@@ -49,6 +49,11 @@ Features added
 * #9195: autodoc: The arguments of ``typing.Literal`` are wrongly rendered
 * #9185: autodoc: :confval:`autodoc_typehints` allows ``'both'`` setting to
   allow typehints to be included both in the signature and description
+* #4257: autodoc: Add :confval:`autodoc_class_signature` to separate the class
+  entry and the definition of ``__init__()`` method
+* #8061, #9218: autodoc: Support variable comment for alias classes
+* #3014: autodoc: Add :event:`autodoc-process-bases` to modify the base classes
+  of the class definitions
 * #3257: autosummary: Support instance attributes for classes
 * #9129: html search: Show search summaries when html_copy_source = False
 * #9120: html theme: Eliminate prompt characters of code-block from copyable
@@ -67,6 +72,10 @@ Bugs fixed
 * #8597: autodoc: a docsting having metadata only should be treated as
   undocumented
 * #9185: autodoc: typehints for overloaded functions and methods are inaccurate
+* #9217: manpage: The name of manpage directory that is generated by
+  :confval:`man_make_section_directory` is not correct
+* #9224: ``:param:`` and ``:type:`` fields does not support a type containing
+  whitespace (ex. ``Dict[str, str]``)
 
 Testing
 --------
@@ -77,9 +86,17 @@ Release 4.0.2 (in development)
 Dependencies
 ------------
 
+* #9216: Support jinja2-3.0
+
 Incompatible changes
 --------------------
 
+* #9222: Update Underscore.js to 1.13.1
+* #9217: manpage: Stop creating a section directory on build manpage by default
+  (see :confval:`man_make_section_directory`)
+* #9240: Unknown node error for pending_xref_condition is raised if an extension
+  that does not support the node installs a missing-reference handler
+
 Deprecated
 ----------
 

diff --git a/EXAMPLES b/EXAMPLES
diff --git a/babel.cfg b/babel.cfg
@@ -1,7 +1,7 @@
 # How to setup this file
-# http://babel.pocoo.org/en/latest/installation.html
+# https://babel.pocoo.org/en/latest/installation.html
 # this file description:
-# http://babel.pocoo.org/en/latest/messages.html
+# https://babel.pocoo.org/en/latest/messages.html
 
 # Extraction from Python source files
 [python: **.py]

diff --git a/doc/_templates/index.html b/doc/_templates/index.html
@@ -29,7 +29,7 @@ <h1>{{ _('Welcome') }}</h1>
     <li>{%trans%}<b>Automatic indices:</b> general index as well as a language-specific
       module indices{%endtrans%}</li>
     <li>{%trans%}<b>Code handling:</b> automatic highlighting using the <a
-      href="http://pygments.org">Pygments</a> highlighter{%endtrans%}</li>
+      href="https://pygments.org">Pygments</a> highlighter{%endtrans%}</li>
     <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>
@@ -38,10 +38,10 @@ <h1>{{ _('Welcome') }}</h1>
       most of them installable from PyPI{%endtrans%}</li>
   </ul>
   <p>{%trans%}
-    Sphinx uses <a href="http://docutils.sourceforge.net/rst.html">reStructuredText</a>
+    Sphinx uses <a href="https://docutils.sourceforge.io/rst.html">reStructuredText</a>
     as its markup language, and many of its strengths come from the power and
     straightforwardness of reStructuredText and its parsing and translating
-    suite, the <a href="http://docutils.sourceforge.net/">Docutils</a>.{%endtrans%}
+    suite, the <a href="https://docutils.sourceforge.io/">Docutils</a>.{%endtrans%}
   </p>
 
   <h2 style="margin-bottom: 0">{%trans%}Documentation{%endtrans%}</h2>

diff --git a/doc/conf.py b/doc/conf.py
@@ -35,7 +35,7 @@
 epub_theme = 'epub'
 epub_basename = 'sphinx'
 epub_author = 'Georg Brandl'
-epub_publisher = 'http://sphinx-doc.org/'
+epub_publisher = 'https://sphinx-doc.org/'
 epub_uid = 'web-site'
 epub_scheme = 'url'
 epub_identifier = epub_publisher
@@ -80,11 +80,11 @@
 autodoc_member_order = 'groupwise'
 autosummary_generate = False
 todo_include_todos = True
-extlinks = {'duref': ('http://docutils.sourceforge.net/docs/ref/rst/'
+extlinks = {'duref': ('https://docutils.sourceforge.io/docs/ref/rst/'
                       'restructuredtext.html#%s', '%s'),
-            'durole': ('http://docutils.sourceforge.net/docs/ref/rst/'
+            'durole': ('https://docutils.sourceforge.io/docs/ref/rst/'
                        'roles.html#%s', '%s'),
-            'dudir': ('http://docutils.sourceforge.net/docs/ref/rst/'
+            'dudir': ('https://docutils.sourceforge.io/docs/ref/rst/'
                       'directives.html#%s', '%s')}
 
 man_pages = [

diff --git a/doc/development/tutorials/helloworld.rst b/doc/development/tutorials/helloworld.rst
@@ -181,9 +181,9 @@ This is the very basic principle of an extension that creates a new directive.
 For a more advanced example, refer to :doc:`todo`.
 
 
-.. _docutils: http://docutils.sourceforge.net/
-.. _docutils directives: http://docutils.sourceforge.net/docs/howto/rst-directives.html
-.. _docutils nodes: http://docutils.sourceforge.net/docs/ref/doctree.html
+.. _docutils: https://docutils.sourceforge.io/
+.. _docutils directives: https://docutils.sourceforge.io/docs/howto/rst-directives.html
+.. _docutils nodes: https://docutils.sourceforge.io/docs/ref/doctree.html
 .. _PyPI: https://pypi.org/
 .. _Python package: https://packaging.python.org/
 .. _Python path: https://docs.python.org/3/using/cmdline.html#envvar-PYTHONPATH
diff --git a/doc/development/tutorials/recipe.rst b/doc/development/tutorials/recipe.rst
@@ -223,4 +223,4 @@ Further reading
 For more information, refer to the `docutils`_ documentation and
 :doc:`/extdev/index`.
 
-.. _docutils: http://docutils.sourceforge.net/docs/
+.. _docutils: https://docutils.sourceforge.io/docs/
diff --git a/doc/development/tutorials/todo.rst b/doc/development/tutorials/todo.rst
@@ -105,7 +105,7 @@ is just a "general" node.
 
    Many extensions will not have to create their own node classes and work fine
    with the nodes already provided by `docutils
-   <http://docutils.sourceforge.net/docs/ref/doctree.html>`__ and :ref:`Sphinx
+   <https://docutils.sourceforge.io/docs/ref/doctree.html>`__ and :ref:`Sphinx
    <nodes>`.
 
 .. attention::
@@ -362,6 +362,6 @@ For more information, refer to the `docutils`_ documentation and
 :doc:`/extdev/index`.
 
 
-.. _docutils: http://docutils.sourceforge.net/docs/
+.. _docutils: https://docutils.sourceforge.io/docs/
 .. _Python path: https://docs.python.org/3/using/cmdline.html#envvar-PYTHONPATH
-.. _docutils documentation: http://docutils.sourceforge.net/docs/ref/rst/directives.html
+.. _docutils documentation: https://docutils.sourceforge.io/docs/ref/rst/directives.html
diff --git a/doc/extdev/i18n.rst b/doc/extdev/i18n.rst
@@ -94,4 +94,4 @@ message catalog template and message catalogs, for example via `Babel`_:
    $ pybabel extract --output=src/locale/myextension.pot src/
    $ pybabel update --input-file=src/locale/myextension.pot --domain=myextension --output-dir=src/locale
 
-.. _Babel: http://babel.pocoo.org/
+.. _Babel: https://babel.pocoo.org/
diff --git a/doc/extdev/index.rst b/doc/extdev/index.rst
@@ -112,7 +112,7 @@ in which a Sphinx project is built: this works in several phases.
    existing files are read, temporary nodes are created.
 
    There are nodes provided by docutils, which are documented `in the docutils
-   documentation <http://docutils.sourceforge.net/docs/ref/doctree.html>`__.
+   documentation <https://docutils.sourceforge.io/docs/ref/doctree.html>`__.
    Additional nodes are provided by Sphinx and :ref:`documented here <nodes>`.
 
    During reading, the build environment is updated with all meta- and cross

diff --git a/doc/extdev/markupapi.rst b/doc/extdev/markupapi.rst
@@ -149,4 +149,4 @@ return ``node.children`` from the Directive.
 
    `Creating directives`_ HOWTO of the Docutils documentation
 
-.. _Creating directives: http://docutils.sourceforge.net/docs/howto/rst-directives.html
+.. _Creating directives: https://docutils.sourceforge.io/docs/howto/rst-directives.html
diff --git a/doc/extdev/parserapi.rst b/doc/extdev/parserapi.rst
@@ -8,7 +8,7 @@ Parser API
     The Parser analyzes the input document and creates a node tree
     representation.
 
-__ http://docutils.sourceforge.net/docs/dev/hacking.html#parsing-the-document
+__ https://docutils.sourceforge.io/docs/dev/hacking.html#parsing-the-document
 
 In Sphinx, the parser modules works as same as docutils.  The parsers are
 registered to Sphinx by extensions using Application APIs;

diff --git a/doc/faq.rst b/doc/faq.rst
@@ -145,7 +145,7 @@ Google Search
 
 .. _Getting Started: https://docs.readthedocs.io/en/stable/intro/getting-started-with-sphinx.html
 .. _api role: https://git.savannah.gnu.org/cgit/kenozooid.git/tree/doc/extapi.py
-.. _xhtml to reST: http://docutils.sourceforge.net/sandbox/xhtml2rest/xhtml2rest.py
+.. _xhtml to reST: https://docutils.sourceforge.io/sandbox/xhtml2rest/xhtml2rest.py
 
 
 Sphinx vs. Docutils
@@ -179,10 +179,10 @@ of the *writers* provided by docutils. This allows Sphinx to provide many
 features that would simply not be possible with docutils, such as those
 outlined above.
 
-__ http://docutils.sourceforge.io/
-__ http://docutils.sourceforge.io/docs/dev/hacking.html
-__ http://docutils.sourceforge.io/rst.html
-__ http://docutils.sourceforge.net/docs/user/tools.html
+__ https://docutils.sourceforge.io/
+__ https://docutils.sourceforge.io/docs/dev/hacking.html
+__ https://docutils.sourceforge.io/rst.html
+__ https://docutils.sourceforge.io/docs/user/tools.html
 
 
 .. _epub-faq:

diff --git a/doc/internals/contributing.rst b/doc/internals/contributing.rst
@@ -251,7 +251,7 @@ The parts of messages in Sphinx that go into builds are translated into several
 locales.  The translations are kept as gettext ``.po`` files translated from the
 master template :file:`sphinx/locale/sphinx.pot`.
 
-Sphinx uses `Babel <http://babel.pocoo.org/en/latest/>`_ to extract messages
+Sphinx uses `Babel <https://babel.pocoo.org/en/latest/>`_ to extract messages
 and maintain the catalog files.  It is integrated in ``setup.py``:
 
 * Use ``python setup.py extract_messages`` to update the ``.pot`` template.
@@ -297,7 +297,7 @@ Debugging tips
   will complain about references without a known target.
 
 * Set the debugging options in the `Docutils configuration file
-  <http://docutils.sourceforge.net/docs/user/config.html>`_.
+  <https://docutils.sourceforge.io/docs/user/config.html>`_.
 
 * JavaScript stemming algorithms in ``sphinx/search/*.py`` (except ``en.py``)
   are generated by this `modified snowballcode generator

diff --git a/doc/make.bat b/doc/make.bat
@@ -19,7 +19,7 @@ if errorlevel 9009 (
 	echo.may add the Sphinx directory to PATH.
 	echo.
 	echo.If you don't have Sphinx installed, grab it from
-	echo.http://sphinx-doc.org/
+	echo.https://sphinx-doc.org/
 	exit /b 1
 )
 

diff --git a/doc/templating.rst b/doc/templating.rst
@@ -6,10 +6,11 @@
 Templating
 ==========
 
-Sphinx uses the `Jinja <http://jinja.pocoo.org>`_ templating engine for its HTML
-templates.  Jinja is a text-based engine, inspired by Django templates, so
-anyone having used Django will already be familiar with it.  It also has
-excellent documentation for those who need to make themselves familiar with it.
+Sphinx uses the `Jinja <https://jinja.palletsprojects.com/>`_ templating engine
+for its HTML templates.  Jinja is a text-based engine, inspired by Django
+templates, so anyone having used Django will already be familiar with it. It
+also has excellent documentation for those who need to make themselves familiar
+with it.
 
 
 Do I need to use Sphinx's templates to produce HTML?

diff --git a/doc/usage/advanced/intl.rst b/doc/usage/advanced/intl.rst
@@ -13,7 +13,7 @@ navigation bars, Sphinx provides mechanisms facilitating the translation of
    :width: 100%
 
    Workflow visualization of translations in Sphinx.  (The figure is created by
-   `plantuml <http://plantuml.com>`_.)
+   `plantuml <https://plantuml.com>`_.)
 
 .. contents::
    :local:

diff --git a/doc/usage/advanced/websupport/quickstart.rst b/doc/usage/advanced/websupport/quickstart.rst
@@ -61,7 +61,7 @@ This will return a dictionary containing the following items:
 
 This dict can then be used as context for templates.  The goal is to be easy to
 integrate with your existing templating system.  An example using `Jinja2
-<http://jinja.pocoo.org/>`_ is:
+<https://jinja.palletsprojects.com/>`_ is:
 
 .. code-block:: html+jinja
 
@@ -112,7 +112,7 @@ must update the websupport package's data::
 should be a boolean representing whether the user has moderation privileges.
 The default value for *moderator* is ``False``.
 
-An example `Flask <http://flask.pocoo.org/>`_ function that checks whether a
+An example `Flask <https://flask.palletsprojects.com/>`_ function that checks whether a
 user is logged in and then retrieves a document is::
 
    from sphinxcontrib.websupport.errors import *
@@ -152,7 +152,7 @@ To use the search form built-in to the Sphinx sidebar, create a function to
 handle requests to the URL 'search' relative to the documentation root.  The
 user's search query will be in the GET parameters, with the key `q`.  Then use
 the :meth:`~sphinxcontrib.websupport.WebSupport.get_search_results` method to
-retrieve search results. In `Flask <http://flask.pocoo.org/>`_ that would be
+retrieve search results. In `Flask <https://flask.palletsprojects.com/>`_ that would be
 like this::
 
    @app.route('/search')

diff --git a/doc/usage/configuration.rst b/doc/usage/configuration.rst
@@ -18,8 +18,8 @@ and output behavior.
   directory to adjust `Docutils`_ configuration if not otherwise overridden or
   set by Sphinx.
 
-  .. _`docutils`: http://docutils.sourceforge.net/
-  .. _`docutils.conf`: http://docutils.sourceforge.net/docs/user/config.html
+  .. _`docutils`: https://docutils.sourceforge.io/
+  .. _`docutils.conf`: https://docutils.sourceforge.io/docs/user/config.html
 
 The configuration file is executed as Python code at build time (using
 :func:`execfile`, and with the current directory set to its containing
@@ -484,7 +484,7 @@ General configuration
    languages, will be used to convert quotes and dashes to typographically
    correct entities.  Default: ``True``.
 
-   __ http://docutils.sourceforge.net/docs/user/smartquotes.html
+   __ https://docutils.sourceforge.io/docs/user/smartquotes.html
    __ https://daringfireball.net/projects/smartypants/
 
    .. versionadded:: 1.6.6
@@ -497,8 +497,8 @@ General configuration
    *deactivates* smart quotes via the corresponding `Docutils option`__.  But
    if it *activates* them, then :confval:`smartquotes` does prevail.
 
-   __ http://docutils.sourceforge.net/docs/user/config.html
-   __ http://docutils.sourceforge.net/docs/user/config.html#smart-quotes
+   __ https://docutils.sourceforge.io/docs/user/config.html
+   __ https://docutils.sourceforge.io/docs/user/config.html#smart-quotes
 
 .. confval:: smartquotes_action
 
@@ -1051,7 +1051,7 @@ that use Sphinx's HTMLWriter class.
    A list of CSS files.  The entry must be a *filename* string or a tuple
    containing the *filename* string and the *attributes* dictionary.  The
    *filename* must be relative to the :confval:`html_static_path`, or a full URI
-   with scheme like ``http://example.org/style.css``.  The *attributes* is used
+   with scheme like ``https://example.org/style.css``.  The *attributes* is used
    for attributes of ``<link>`` tag.  It defaults to an empty list.
 
    Example::
@@ -1074,7 +1074,7 @@ that use Sphinx's HTMLWriter class.
    A list of JavaScript *filename*.  The entry must be a *filename* string or a
    tuple containing the *filename* string and the *attributes* dictionary.  The
    *filename* must be relative to the :confval:`html_static_path`, or a full
-   URI with scheme like ``http://example.org/script.js``.  The *attributes* is
+   URI with scheme like ``https://example.org/script.js``.  The *attributes* is
    used for attributes of ``<script>`` tag.  It defaults to an empty list.
 
    Example::
@@ -1308,7 +1308,7 @@ that use Sphinx's HTMLWriter class.
 
 .. confval:: html_use_opensearch
 
-   If nonempty, an `OpenSearch <http://www.opensearch.org/Home>`_ description
+   If nonempty, an `OpenSearch <https://www.opensearch.org/>`_ description
    file will be output, and all pages will contain a ``<link>`` tag referring
    to it.  Since OpenSearch doesn't support relative URLs for its search page
    location, the value of this option must be the base URL from which these
@@ -1735,7 +1735,7 @@ Options for epub output
 These options influence the epub output.  As this builder derives from the HTML
 builder, the HTML options also apply where appropriate.  The actual values for
 some of the options is not really important, they just have to be entered into
-the `Dublin Core metadata <http://dublincore.org/>`_.
+the `Dublin Core metadata <https://dublincore.org/>`_.
 
 .. confval:: epub_basename
 
@@ -2357,6 +2357,10 @@ These options influence manual page output.
 
       The default is changed to ``False`` from ``True``.
 
+   .. versionchanged:: 4.0.2
+
+      The default is changed to ``True`` from ``False`` again.
+
 .. _texinfo-options:
 
 Options for Texinfo output
@@ -2592,7 +2596,7 @@ Options for the linkcheck builder
       as follows::
 
          linkcheck_ignore = [
-            'http://www.sphinx-doc.org/en/1.7/intro.html#'
+            'https://www.sphinx-doc.org/en/1.7/intro.html#'
          ]
 
    .. versionadded:: 1.5

diff --git a/doc/usage/extensions/autodoc.rst b/doc/usage/extensions/autodoc.rst
@@ -463,6 +463,20 @@ There are also config values that you can set:
 
    .. versionadded:: 1.4
 
+.. confval:: autodoc_class_signature
+
+   This value selects how the signautre will be displayed for the class defined
+   by :rst:dir:`autoclass` directive.  The possible values are:
+
+   ``"mixed"``
+      Display the signature with the class name.
+   ``"separated"``
+      Display the signature as a method.
+
+   The default is ``"mixed"``.
+
+   .. versionadded:: 4.1
+
 .. confval:: autodoc_member_order
 
    This value selects if automatically documented members are sorted
@@ -749,6 +763,21 @@ needed docstring processing in event :event:`autodoc-process-docstring`:
 .. autofunction:: cut_lines
 .. autofunction:: between
 
+.. event:: autodoc-process-bases (app, name, obj, options, bases)
+
+   .. versionadded:: 4.1
+
+   Emitted when autodoc has read and processed a class to determine the
+   base-classes.  *bases* is a list of classes that the event handler can
+   modify **in place** to change what Sphinx puts into the output.  It's
+   emitted only if ``show-inheritance`` option given.
+
+   :param app: the Sphinx application object
+   :param name: the fully qualified name of the object
+   :param obj: the object itself
+   :param options: the options given to the class directive
+   :param bases: the list of base classes signature. see above.
+
 
 Skipping members
 ----------------