Merge branch '3.x' into master

CHANGES

@@ -58,6 +58,8 @@ Deprecated
 
 * ``sphinx.builders.latex.LaTeXBuilder.usepackages``
 * ``sphinx.builders.latex.LaTeXBuilder.usepackages_afger_hyperref``
+* ``sphinx.ext.autodoc.SingledispatchFunctionDocumenter``
+* ``sphinx.ext.autodoc.SingledispatchMethodDocumenter``
 
 Features added
 --------------
@@ -68,25 +70,36 @@ Features added
   nested declarations.
 * #8081: LaTeX: Allow to add LaTeX package via ``app.add_latex_package()`` until
   just before writing .tex file
+* #7996: manpage: Add :confval:`man_make_section_directory` to make a section
+  directory on build man page
 
 Bugs fixed
 ----------
 
 * #8085: i18n: Add support for having single text domain
+* #6640: i18n: Failed to override system message translation
 * #8143: autodoc: AttributeError is raised when False value is passed to
   autodoc_default_options
 * #8103: autodoc: functools.cached_property is not considered as a property
 * #8190: autodoc: parsing error is raised if some extension replaces docstring
   by string not ending with blank lines
 * #8142: autodoc: Wrong constructor signature for the class derived from
   typing.Generic
+* #8157: autodoc: TypeError is raised when annotation has invalid __args__
+* #7964: autodoc: Tuple in default value is wrongly rendered
 * #8192: napoleon: description is disappeared when it contains inline literals
 * #8142: napoleon: Potential of regex denial of service in google style docs
 * #8169: LaTeX: pxjahyper loaded even when latex_engine is not platex
 * #8175: intersphinx: Potential of regex denial of service by broken inventory
+* #8277: sphinx-build: missing and redundant spacing (and etc) for console
+  output on building
+* #7973: imgconverter: Check availability of imagemagick many times
 * #8093: The highlight warning has wrong location in some builders (LaTeX,
   singlehtml and so on)
 * #8239: Failed to refer a token in productionlist if it is indented
+* #8268: linkcheck: Report HTTP errors when ``linkcheck_anchors`` is ``True``
+* #8245: linkcheck: take source directory into account for local files
+* #6914: figure numbers are unexpectedly assigned to uncaptioned items
 
 Testing
 --------
@@ -217,7 +230,7 @@ Bugs fixed
   contains a hyperlink target
 * #7469: autosummary: "Module attributes" header is not translatable
 * #7940: apidoc: An extra newline is generated at the end of the rst file if a
-  module has submodules 
+  module has submodules
 * #4258: napoleon: decorated special methods are not shown
 * #7799: napoleon: parameters are not escaped for combined params in numpydoc
 * #7780: napoleon: multiple paramaters declaration in numpydoc was wrongly
@@ -384,7 +397,7 @@ Features added
 * #7543: html theme: Add top and bottom margins to tables
 * #7695: html theme: Add viewport meta tag for basic theme
 * #7721: html theme: classic: default codetextcolor/codebgcolor doesn't override
-  Pygments 
+  Pygments
 * C and C++: allow semicolon in the end of declarations.
 * C++, parse parameterized noexcept specifiers.
 * #7294: C++, parse expressions with user-defined literals.

doc/_themes/sphinx13/static/sphinx13.css

@@ -239,7 +239,7 @@ div.footer a {
 
 /* -- body styles ----------------------------------------------------------- */
 
-p {    
+p {
     margin: 0.8em 0 0.5em 0;
 }
 

doc/extdev/deprecated.rst

@@ -66,6 +66,16 @@ The following is a list of deprecated interfaces.
      - 5.0
      - N/A
 
+   * - ``sphinx.ext.autodoc.SingledispatchFunctionDocumenter``
+     - 3.3
+     - 5.0
+     - ``sphinx.ext.autodoc.FunctionDocumenter``
+
+   * - ``sphinx.ext.autodoc.SingledispatchMethodDocumenter``
+     - 3.3
+     - 5.0
+     - ``sphinx.ext.autodoc.MethodDocumenter``
+
    * - ``sphinx.ext.autodoc.members_set_option()``
      - 3.2
      - 5.0

doc/usage/configuration.rst

@@ -2246,6 +2246,12 @@ These options influence manual page output.
 
    .. versionadded:: 1.1
 
+.. confval:: man_make_section_directory
+
+   If true, make a section directory on build man page.  Default is False.
+
+   .. versionadded:: 3.3
+
 
 .. _texinfo-options:
 

doc/usage/extensions/autodoc.rst

@@ -515,6 +515,44 @@ There are also config values that you can set:
 
       New option ``'description'`` is added.
 
+.. confval:: autodoc_type_aliases
+
+   A dictionary for users defined `type aliases`__ that maps a type name to the
+   full-qualified object name.  It is used to keep type aliases not evaluated in
+   the document.  Defaults to empty (``{}``).
+
+   The type aliases are only available if your program enables `Postponed
+   Evaluation of Annotations (PEP 563)`__ feature via ``from __future__ import
+   annotations``.
+
+   For example, there is code using a type alias::
+
+     from __future__ import annotations
+
+     AliasType = Union[List[Dict[Tuple[int, str], Set[int]]], Tuple[str, List[str]]]
+
+     def f() -> AliasType:
+         ...
+
+   If ``autodoc_type_aliases`` is not set, autodoc will generate internal mark-up
+   from this code as following::
+
+     .. py:function:: f() -> Union[List[Dict[Tuple[int, str], Set[int]]], Tuple[str, List[str]]]
+
+        ...
+
+   If you set ``autodoc_type_aliases`` as
+   ``{'AliasType': 'your.module.TypeAlias'}``, it generates a following document
+   internally::
+
+     .. py:function:: f() -> your.module.AliasType:
+
+        ...
+
+   .. __: https://www.python.org/dev/peps/pep-0563/
+   .. __: https://mypy.readthedocs.io/en/latest/kinds_of_types.html#type-aliases
+   .. versionadded:: 3.3
+
 .. confval:: autodoc_warningiserror
 
    This value controls the behavior of :option:`sphinx-build -W` during

doc/usage/extensions/coverage.rst

@@ -51,7 +51,7 @@ should check:
 
    .. versionadded:: 1.1
 
-.. confval:: coverage_show_missing_items 
+.. confval:: coverage_show_missing_items
 
    Print objects that are missing to standard output also.
    ``False`` by default.

doc/usage/installation.rst

@@ -171,7 +171,7 @@ Docker images for Sphinx are published on the `Docker Hub <https://hub.docker.co
 - `sphinxdoc/sphinx <https://hub.docker.com/repository/docker/sphinxdoc/sphinx>`_
 - `sphinxdoc/sphinx-latexpdf <https://hub.docker.com/repository/docker/sphinxdoc/sphinx-latexpdf>`_
 
-Former one is used for standard usage of Sphinx, and latter one is mainly used for PDF builds using LaTeX. 
+Former one is used for standard usage of Sphinx, and latter one is mainly used for PDF builds using LaTeX.
 Please choose one for your purpose.
 
 .. note::

doc/usage/restructuredtext/directives.rst

@@ -665,7 +665,7 @@ __ http://pygments.org/docs/lexers
    .. note::
 
       If you want to select only ``[second-section]`` of ini file like the
-      following, you can use ``:start-at: [second-section]`` and 
+      following, you can use ``:start-at: [second-section]`` and
       ``:end-before: [third-section]``:
 
       .. code-block:: ini
@@ -692,7 +692,7 @@ __ http://pygments.org/docs/lexers
              # [initialize]
              app.start(":8000")
              # [initialize]
-     
+
 
    When lines have been selected in any of the ways described above, the line
    numbers in ``emphasize-lines`` refer to those selected lines, counted

sphinx/application.py

@@ -17,7 +17,7 @@
 from collections import deque
 from io import StringIO
 from os import path
-from typing import Any, Callable, Dict, IO, List, Tuple, Type, Union
+from typing import Any, Callable, Dict, IO, List, Optional, Tuple, Type, Union
 from typing import TYPE_CHECKING
 
 from docutils import nodes
@@ -289,7 +289,10 @@ def _init_i18n(self) -> None:
                 if catalog.domain == 'sphinx' and catalog.is_outdated():
                     catalog.write_mo(self.config.language)
 
-            locale_dirs = [None, path.join(package_dir, 'locale')] + list(repo.locale_dirs)
+            locale_dirs = [None]  # type: List[Optional[str]]
+            locale_dirs += list(repo.locale_dirs)
+            locale_dirs += [path.join(package_dir, 'locale')]
+
             self.translator, has_translation = locale.init(locale_dirs, self.config.language)
             if has_translation or self.config.language == 'en':
                 # "en" never needs to be translated

sphinx/builders/html/__init__.py

@@ -646,17 +646,17 @@ def gen_pages_from_extensions(self) -> None:
     def gen_additional_pages(self) -> None:
         # additional pages from conf.py
         for pagename, template in self.config.html_additional_pages.items():
-            logger.info(' ' + pagename, nonl=True)
+            logger.info(pagename + ' ', nonl=True)
             self.handle_page(pagename, {}, template)
 
         # the search page
         if self.search:
-            logger.info(' search', nonl=True)
+            logger.info('search ', nonl=True)
             self.handle_page('search', {}, 'search.html')
 
         # the opensearch xml file
         if self.config.html_use_opensearch and self.search:
-            logger.info(' opensearch', nonl=True)
+            logger.info('opensearch ', nonl=True)
             fn = path.join(self.outdir, '_static', 'opensearch.xml')
             self.handle_page('opensearch', {}, 'opensearch.xml', outfilename=fn)
 
@@ -674,7 +674,7 @@ def write_genindex(self) -> None:
             'genindexcounts': indexcounts,
             'split_index': self.config.html_split_index,
         }
-        logger.info(' genindex', nonl=True)
+        logger.info('genindex ', nonl=True)
 
         if self.config.html_split_index:
             self.handle_page('genindex', genindexcontext,
@@ -696,7 +696,7 @@ def write_domain_indices(self) -> None:
                 'content': content,
                 'collapse_index': collapse,
             }
-            logger.info(' ' + indexname, nonl=True)
+            logger.info(indexname + ' ', nonl=True)
             self.handle_page(indexname, indexcontext, 'domainindex.html')
 
     def copy_image_files(self) -> None:
@@ -790,7 +790,7 @@ def copy_html_favicon(self) -> None:
 
     def copy_static_files(self) -> None:
         try:
-            with progress_message(__('copying static files... ')):
+            with progress_message(__('copying static files')):
                 ensuredir(path.join(self.outdir, '_static'))
 
                 # prepare context for templates

sphinx/builders/latex/__init__.py

@@ -474,7 +474,7 @@ def validate_latex_theme_options(app: Sphinx, config: Config) -> None:
             config.latex_theme_options.pop(key)
 
 
-def install_pakcages_for_ja(app: Sphinx) -> None:
+def install_packages_for_ja(app: Sphinx) -> None:
     """Install packages for Japanese."""
     if app.config.language == 'ja' and app.config.latex_engine in ('platex', 'uplatex'):
         app.add_latex_package('pxjahyper', after_hyperref=True)
@@ -527,7 +527,7 @@ def setup(app: Sphinx) -> Dict[str, Any]:
     app.add_builder(LaTeXBuilder)
     app.connect('config-inited', validate_config_values, priority=800)
     app.connect('config-inited', validate_latex_theme_options, priority=800)
-    app.connect('builder-inited', install_pakcages_for_ja)
+    app.connect('builder-inited', install_packages_for_ja)
 
     app.add_config_value('latex_engine', default_latex_engine, None,
                          ENUM('pdflatex', 'xelatex', 'lualatex', 'platex', 'uplatex'))

sphinx/builders/linkcheck.py

@@ -166,6 +166,7 @@ def check_uri() -> Tuple[str, str, int]:
                     # Read the whole document and see if #anchor exists
                     response = requests.get(req_url, stream=True, config=self.app.config,
                                             auth=auth_info, **kwargs)
+                    response.raise_for_status()
                     found = check_anchor(response, unquote(anchor))
 
                     if not found:
@@ -210,7 +211,7 @@ def check_uri() -> Tuple[str, str, int]:
                 else:
                     return 'redirected', new_url, 0
 
-        def check() -> Tuple[str, str, int]:
+        def check(docname: str) -> Tuple[str, str, int]:
             # check for various conditions without bothering the network
             if len(uri) == 0 or uri.startswith(('#', 'mailto:')):
                 return 'unchecked', '', 0
@@ -219,7 +220,8 @@ def check() -> Tuple[str, str, int]:
                     # non supported URI schemes (ex. ftp)
                     return 'unchecked', '', 0
                 else:
-                    if path.exists(path.join(self.srcdir, uri)):
+                    srcdir = path.dirname(self.env.doc2path(docname))
+                    if path.exists(path.join(srcdir, uri)):
                         return 'working', '', 0
                     else:
                         for rex in self.to_ignore:
@@ -256,7 +258,7 @@ def check() -> Tuple[str, str, int]:
             uri, docname, lineno = self.wqueue.get()
             if uri is None:
                 break
-            status, info, code = check()
+            status, info, code = check(docname)
             self.rqueue.put((uri, docname, lineno, status, info, code))
 
     def process_result(self, result: Tuple[str, str, int, str, str, int]) -> None:

sphinx/builders/manpage.py

@@ -24,7 +24,7 @@
 from sphinx.util import progress_message
 from sphinx.util.console import darkgreen  # type: ignore
 from sphinx.util.nodes import inline_all_toctrees
-from sphinx.util.osutil import make_filename_from_project
+from sphinx.util.osutil import ensuredir, make_filename_from_project
 from sphinx.writers.manpage import ManualPageWriter, ManualPageTranslator
 
 
@@ -80,7 +80,12 @@ def write(self, *ignored: Any) -> None:
             docsettings.authors = authors
             docsettings.section = section
 
-            targetname = '%s.%s' % (name, section)
+            if self.config.man_make_section_directory:
+                ensuredir(path.join(self.outdir, str(section)))
+                targetname = '%s/%s.%s' % (section, name, section)
+            else:
+                targetname = '%s.%s' % (name, section)
+
             logger.info(darkgreen(targetname) + ' { ', nonl=True)
             destination = FileOutput(
                 destination_path=path.join(self.outdir, targetname),
@@ -115,6 +120,7 @@ def setup(app: Sphinx) -> Dict[str, Any]:
 
     app.add_config_value('man_pages', default_man_pages, None)
     app.add_config_value('man_show_urls', False, None)
+    app.add_config_value('man_make_section_directory', False, None)
 
     return {
         'version': 'builtin',

sphinx/environment/collectors/toctree.py

@@ -220,6 +220,10 @@ def assign_figure_numbers(self, env: BuildEnvironment) -> List[str]:
         def get_figtype(node: Node) -> str:
             for domain in env.domains.values():
                 figtype = domain.get_enumerable_node_type(node)
+                if domain.name == 'std' and not domain.get_numfig_title(node):  # type: ignore
+                    # Skip if uncaptioned node
+                    continue
+
                 if figtype:
                     return figtype