Merge branch '4.x' into 4.x

.github/ISSUE_TEMPLATE/bug-report.yml

@@ -16,7 +16,6 @@ body:
       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

CHANGES

@@ -13,13 +13,30 @@ Deprecated
 Features added
 --------------
 
+* #9445: autodoc: Support class properties
+* #9479: autodoc: Emit a warning if target is a mocked object
+* #9447: html theme: Expose the version of Sphinx in the form of tuple as a
+  template variable ``sphinx_version_tuple``
+* #9445: py domain: ``:py:property:`` directive supports ``:classmethod:``
+  option to describe the class property
+
 Bugs fixed
 ----------
 
+* #9487: autodoc: typehint for cached_property is not shown
+* #9509: autodoc: AttributeError is raised on failed resolving typehints
+* #9518: autodoc: autodoc_docstring_signature does not effect to ``__init__()``
+  and ``__new__()``
+* #9481: autosummary: some warnings contain non-existing filenames
+* #9481: c domain: some warnings contain non-existing filenames
+* #9481: cpp domain: some warnings contain non-existing filenames
+* #9456: html search: abbreation marks are inserted to the search result if
+  failed to fetch the content of the page
+
 Testing
 --------
 
-Release 4.1.2 (in development)
+Release 4.1.3 (in development)
 ==============================
 
 Dependencies
@@ -37,9 +54,31 @@ Features added
 Bugs fixed
 ----------
 
+* #9512: sphinx-build: crashed with the HEAD of Python 3.10
+
 Testing
 --------
 
+Release 4.1.2 (released Jul 27, 2021)
+=====================================
+
+Incompatible changes
+--------------------
+
+* #9435: linkcheck: Disable checking automatically generated anchors on
+  github.com (ex. anchors in reST/Markdown documents)
+
+Bugs fixed
+----------
+
+* #9489: autodoc: Custom types using ``typing.NewType`` are not displayed well
+  with the HEAD of 3.10
+* #9490: autodoc: Some objects under ``typing`` module are not displayed well
+  with the HEAD of 3.10
+* #9436, #9471: autodoc: crashed if ``autodoc_class_signature = "separated"``
+* #9456: html search: html_copy_source can't control the search summaries
+* #9435: linkcheck: Failed to check anchors in github.com
+
 Release 4.1.1 (released Jul 15, 2021)
 =====================================
 

doc/latex.rst

@@ -1151,6 +1151,20 @@ Miscellany
      Formerly, use of *fncychap* with other styles than ``Bjarne`` was
      dysfunctional.
 
+- 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
+  ``sphinxclassfoo``.  A simple example would be:
+
+  .. code-block:: latex
+
+     \newenvironment{sphinxclassred}{\color{red}}{}
+
+  Currently the class names must contain only ascii characters and avoid
+  characters special to LaTeX such as ``\``.
+
+  .. versionadded:: 4.1.0
+
 .. hint::
 
    As an experimental feature, Sphinx can use user-defined template file for

doc/templating.rst

@@ -372,7 +372,16 @@ in the future.
 
 .. data:: sphinx_version
 
-   The version of Sphinx used to build.
+   The version of Sphinx used to build represented as a string for example "3.5.1".
+
+.. data:: sphinx_version_tuple
+
+   The version of Sphinx used to build represented as a tuple of five elements.
+   For Sphinx version 3.5.1 beta 3 this would be `(3, 5, 1, 'beta', 3)``.
+   The fourth element can be one of: ``alpha``, ``beta``, ``rc``, ``final``.
+   ``final`` always has 0 as the last element.
+
+   .. versionadded:: 4.2
 
 .. data:: style
 

doc/tutorial/index.rst

@@ -233,7 +233,7 @@ Sweet!
 .. note::
 
    Generating a PDF using Sphinx can be done running ``make latexpdf``,
-   provided that the system has a working :math:`\LaTeX` installation,
+   provided that the system has a working LaTeX installation,
    as explained in the documentation of :class:`sphinx.builders.latex.LaTeXBuilder`.
    Although this is perfectly feasible, such installations are often big,
    and in general LaTeX requires careful configuration in some cases,

doc/usage/extensions/autodoc.rst

@@ -353,6 +353,7 @@ inserting them into the page source under a suitable :rst:dir:`py:module`,
                    autodata
                    automethod
                    autoattribute
+                   autoproperty
 
    These work exactly like :rst:dir:`autoclass` etc.,
    but do not offer the options used for automatic member documentation.
@@ -422,6 +423,8 @@ inserting them into the page source under a suitable :rst:dir:`py:module`,
       option.
    .. versionchanged:: 2.0
       :rst:dir:`autodecorator` added.
+   .. versionchanged:: 2.1
+      :rst:dir:`autoproperty` added.
    .. versionchanged:: 3.4
       :rst:dir:`autodata` and :rst:dir:`autoattribute` now have a ``no-value``
       option.

doc/usage/restructuredtext/domains.rst

@@ -329,6 +329,13 @@ The following directives are provided for module and class contents:
 
       Indicate the property is abstract.
 
+   .. rst:directive:option:: classmethod
+      :type: no value
+
+      Indicate the property is a classmethod.
+
+      .. versionaddedd: 4.2
+
    .. rst:directive:option:: type: type of the property
       :type: text
 

sphinx/application.py

@@ -197,7 +197,7 @@ def __init__(self, srcdir: str, confdir: Optional[str], outdir: str, doctreedir:
 
         # notice for parallel build on macOS and py38+
         if sys.version_info > (3, 8) and platform.system() == 'Darwin' and parallel > 1:
-            logger.info(bold(__("For security reason, parallel mode is disabled on macOS and "
+            logger.info(bold(__("For security reasons, parallel mode is disabled on macOS and "
                                 "python3.8 and above. For more details, please read "
                                 "https://github.com/sphinx-doc/sphinx/issues/6803")))
 
@@ -415,7 +415,7 @@ def connect(self, event: str, callback: Callable, priority: int = 500) -> int:
         :param event: The name of target event
         :param callback: Callback function for the event
         :param priority: The priority of the callback.  The callbacks will be invoked
-                         in the order of *priority* in asending.
+                         in order of *priority* (ascending).
         :return: A listener ID.  It can be used for :meth:`disconnect`.
 
         .. versionchanged:: 3.0
@@ -493,7 +493,7 @@ def add_config_value(self, name: str, default: Any, rebuild: Union[bool, str],
         values accordingly.
 
 
-        :param name: The name of configuration value.  It is recommended to be prefixed
+        :param name: The name of the configuration value.  It is recommended to be prefixed
                      with the extension name (ex. ``html_logo``, ``epub_title``)
         :param default: The default value of the configuration.
         :param rebuild: The condition of rebuild.  It must be one of those values:
@@ -539,10 +539,10 @@ def set_translator(self, name: str, translator_class: Type[nodes.NodeVisitor],
         """Register or override a Docutils translator class.
 
         This is used to register a custom output translator or to replace a
-        builtin translator.  This allows extensions to use custom translator
+        builtin translator.  This allows extensions to use a custom translator
         and define custom nodes for the translator (see :meth:`add_node`).
 
-        :param name: The name of builder for the translator
+        :param name: The name of the builder for the translator
         :param translator_class: A translator class
         :param override: If true, install the translator forcedly even if another translator
                          is already installed as the same name
@@ -606,11 +606,11 @@ def add_enumerable_node(self, node: Type[Element], figtype: str,
         using :rst:role:`numref`.
 
         :param node: A node class
-        :param figtype: The type of enumerable nodes.  Each figtypes have individual numbering
-                        sequences.  As a system figtypes, ``figure``, ``table`` and
-                        ``code-block`` are defined.  It is able to add custom nodes to these
-                        default figtypes.  It is also able to define new custom figtype if new
-                        figtype is given.
+        :param figtype: The type of enumerable nodes.  Each figtype has individual numbering
+                        sequences.  As system figtypes, ``figure``, ``table`` and
+                        ``code-block`` are defined.  It is possible to add custom nodes to
+                        these default figtypes.  It is also possible to define new custom
+                        figtype if a new figtype is given.
         :param title_getter: A getter function to obtain the title of node.  It takes an
                              instance of the enumerable node, and it must return its title as
                              string.  The title is used to the default title of references for
@@ -629,7 +629,7 @@ def add_enumerable_node(self, node: Type[Element], figtype: str,
     def add_directive(self, name: str, cls: Type[Directive], override: bool = False) -> None:
         """Register a Docutils directive.
 
-        :param name: The name of directive
+        :param name: The name of the directive
         :param cls: A directive class
         :param override: If true, install the directive forcedly even if another directive
                          is already installed as the same name
@@ -755,9 +755,9 @@ def add_role_to_domain(self, domain: str, name: str, role: Union[RoleFunction, X
         Like :meth:`add_role`, but the role is added to the domain named
         *domain*.
 
-        :param domain: The name of target domain
-        :param name: A name of role
-        :param role: A role function
+        :param domain: The name of the target domain
+        :param name: The name of the role
+        :param role: The role function
         :param override: If true, install the role forcedly even if another role is already
                          installed as the same name
 
@@ -773,8 +773,8 @@ def add_index_to_domain(self, domain: str, index: Type[Index], override: bool =
 
         Add a custom *index* class to the domain named *domain*.
 
-        :param domain: The name of target domain
-        :param index: A index class
+        :param domain: The name of the target domain
+        :param index: The index class
         :param override: If true, install the index forcedly even if another index is
                          already installed as the same name
 
@@ -942,8 +942,8 @@ def add_js_file(self, filename: str, priority: int = 500, **kwargs: Any) -> None
         Add *filename* to the list of JavaScript files that the default HTML
         template will include in order of *priority* (ascending).  The filename
         must be relative to the HTML static path , or a full URI with scheme.
-        If the priority of JavaScript file is the same as others, the JavaScript
-        files will be included in order of the registration.  If the keyword
+        If the priority of the JavaScript file is the same as others, the JavaScript
+        files will be included in order of registration.  If the keyword
         argument ``body`` is given, its value will be added between the
         ``<script>`` tags. Extra keyword arguments are included as attributes of
         the ``<script>`` tag.
@@ -971,7 +971,7 @@ def add_js_file(self, filename: str, priority: int = 500, **kwargs: Any) -> None
            * - 800
              - default priority for :confval:`html_js_files`
 
-        A JavaScript file can be added to the specific HTML page when on extension
+        A JavaScript file can be added to the specific HTML page when an extension
         calls this method on :event:`html-page-context` event.
 
         .. versionadded:: 0.5
@@ -993,8 +993,8 @@ def add_css_file(self, filename: str, priority: int = 500, **kwargs: Any) -> Non
         Add *filename* to the list of CSS files that the default HTML template
         will include in order of *priority* (ascending).  The filename must be
         relative to the HTML static path, or a full URI with scheme.  If the
-        priority of CSS file is the same as others, the CSS files will be
-        included in order of the registration.  The keyword arguments are also
+        priority of the CSS file is the same as others, the CSS files will be
+        included in order of registration.  The keyword arguments are also
         accepted for attributes of ``<link>`` tag.
 
         Example::
@@ -1022,15 +1022,15 @@ def add_css_file(self, filename: str, priority: int = 500, **kwargs: Any) -> Non
            * - 800
              - default priority for :confval:`html_css_files`
 
-        A CSS file can be added to the specific HTML page when on extension calls
+        A CSS file can be added to the specific HTML page when an extension calls
         this method on :event:`html-page-context` event.
 
         .. versionadded:: 1.0
 
         .. versionchanged:: 1.6
            Optional ``alternate`` and/or ``title`` attributes can be supplied
-           with the *alternate* (of boolean type) and *title* (a string)
-           arguments. The default is no title and *alternate* = ``False``. For
+           with the arguments *alternate* (a Boolean) and *title* (a string).
+           The default is no title and *alternate* = ``False``. For
            more information, refer to the `documentation
            <https://mdn.io/Web/CSS/Alternative_style_sheets>`__.
 
@@ -1051,7 +1051,7 @@ def add_latex_package(self, packagename: str, options: str = None,
         r"""Register a package to include in the LaTeX source code.
 
         Add *packagename* to the list of packages that LaTeX source code will
-        include.  If you provide *options*, it will be taken to `\usepackage`
+        include.  If you provide *options*, it will be taken to the `\usepackage`
         declaration.  If you set *after_hyperref* truthy, the package will be
         loaded after ``hyperref`` package.
 
@@ -1087,7 +1087,7 @@ def add_autodocumenter(self, cls: Any, override: bool = False) -> None:
 
         Add *cls* as a new documenter class for the :mod:`sphinx.ext.autodoc`
         extension.  It must be a subclass of
-        :class:`sphinx.ext.autodoc.Documenter`.  This allows to auto-document
+        :class:`sphinx.ext.autodoc.Documenter`.  This allows auto-documenting
         new types of objects.  See the source of the autodoc module for
         examples on how to subclass :class:`Documenter`.
 
@@ -1140,10 +1140,10 @@ def add_source_suffix(self, suffix: str, filetype: str, override: bool = False)
         """Register a suffix of source files.
 
         Same as :confval:`source_suffix`.  The users can override this
-        using the setting.
+        using the config setting.
 
         If *override* is True, the given *suffix* is forcedly installed even if
-        a same suffix is already installed.
+        the same suffix is already installed.
 
         .. versionadded:: 1.8
         """
@@ -1204,8 +1204,8 @@ def add_html_math_renderer(self, name: str,
     def add_message_catalog(self, catalog: str, locale_dir: str) -> None:
         """Register a message catalog.
 
-        :param catalog: A name of catalog
-        :param locale_dir: The base path of message catalog
+        :param catalog: The name of the catalog
+        :param locale_dir: The base path of the message catalog
 
         For more details, see :func:`sphinx.locale.get_translation()`.
 
@@ -1216,7 +1216,7 @@ def add_message_catalog(self, catalog: str, locale_dir: str) -> None:
 
     # ---- other methods -------------------------------------------------
     def is_parallel_allowed(self, typ: str) -> bool:
-        """Check parallel processing is allowed or not.
+        """Check whether parallel processing is allowed or not.
 
         :param typ: A type of processing; ``'read'`` or ``'write'``.
         """

sphinx/builders/html/__init__.py

@@ -26,6 +26,7 @@
 from docutils.utils import relative_path
 
 from sphinx import __display_version__, package_dir
+from sphinx import version_info as sphinx_version
 from sphinx.application import Sphinx
 from sphinx.builders import Builder
 from sphinx.config import ENUM, Config
@@ -516,6 +517,7 @@ def prepare_writing(self, docnames: Set[str]) -> None:
             'language': self.config.language,
             'css_files': self.css_files,
             'sphinx_version': __display_version__,
+            'sphinx_version_tuple': sphinx_version,
             'style': self._get_style_filename(),
             'rellinks': rellinks,
             'builder': self.name,

sphinx/builders/linkcheck.py

@@ -714,7 +714,10 @@ def setup(app: Sphinx) -> Dict[str, Any]:
     app.add_event('linkcheck-process-uri')
 
     app.connect('config-inited', compile_linkcheck_allowed_redirects, priority=800)
-    app.connect('linkcheck-process-uri', rewrite_github_anchor)
+
+    # FIXME: Disable URL rewrite handler for github.com temporarily.
+    # ref: https://github.com/sphinx-doc/sphinx/issues/9435
+    # app.connect('linkcheck-process-uri', rewrite_github_anchor)
 
     return {
         'version': 'builtin',