Merge branch '3.x'

CHANGES

@@ -74,16 +74,25 @@ Incompatible changes
 Deprecated
 ----------
 
+* pending_xref node for viewcode extension
+* ``sphinx.builders.linkcheck.CheckExternalLinksBuilder.broken``
+* ``sphinx.builders.linkcheck.CheckExternalLinksBuilder.good``
+* ``sphinx.builders.linkcheck.CheckExternalLinksBuilder.redirected``
+* ``sphinx.builders.linkcheck.node_line_or_0()``
 * ``sphinx.ext.autodoc.AttributeDocumenter.isinstanceattribute()``
 * ``sphinx.ext.autodoc.directive.DocumenterBridge.reporter``
 * ``sphinx.ext.autodoc.importer.get_module_members()``
+* ``sphinx.ext.autosummary.generate._simple_info()``
+* ``sphinx.ext.autosummary.generate._simple_warn()``
 
 Features added
 --------------
 
 * #8022: autodoc: autodata and autoattribute directives does not show right-hand
   value of the variable if docstring contains ``:meta hide-value:`` in
   info-field-list
+* #8514: autodoc: Default values of overloaded functions are taken from actual
+  implementation if they're ellipsis
 * #8619: html: kbd role generates customizable HTML tags for compound keys
 * #8634: html: Allow to change the order of JS/CSS via ``priority`` parameter
   for :meth:`Sphinx.add_js_file()` and :meth:`Sphinx.add_css_file()`
@@ -92,12 +101,16 @@ Features added
   :event:`html-page-context` event
 * #8649: imgconverter: Skip availability check if builder supports the image
   type
+* #8573: napoleon: Allow to change the style of custom sections using
+  :confval:`napoleon_custom_styles`
 * #6241: mathjax: Include mathjax.js only on the document using equations
 * #8651: std domain: cross-reference for a rubric having inline item is broken
+* #8681: viewcode: Support incremental build
 * #8132: Add :confval:`project_copyright` as an alias of :confval:`copyright`
 * #207: Now :confval:`highlight_language` supports multiple languages
 * #2030: :rst:dir:`code-block` and :rst:dir:`literalinclude` supports automatic
   dedent via no-argument ``:dedent:`` option
+* C++, also hyperlink operator overloads in expressions and alias declarations.
 
 Bugs fixed
 ----------
@@ -109,19 +122,27 @@ Bugs fixed
 * #8315: autodoc: Failed to resolve struct.Struct type annotation
 * #8652: autodoc: All variable comments in the module are ignored if the module
   contains invalid type comments
+* #8693: autodoc: Default values for overloaded functions are rendered as string
 * #8306: autosummary: mocked modules are documented as empty page when using
   :recursive: option
 * #8618: html: kbd role produces incorrect HTML when compound-key separators (-,
   + or ^) are used as keystrokes
 * #8629: html: A type warning for html_use_opensearch is shown twice
+* #8714: html: kbd role with "Caps Lock" rendered incorrectly
 * #8665: html theme: Could not override globaltoc_maxdepth in theme.conf
+* #4304: linkcheck: Fix race condition that could lead to checking the
+  availability of the same URL twice
 * #8094: texinfo: image files on the different directory with document are not
   copied
+* #8720: viewcode: module pages are generated for epub on incremental build
+* #8704: viewcode: anchors are generated in incremental build after singlehtml
 * #8671: :confval:`highlight_options` is not working
 * #8341: C, fix intersphinx lookup types for names in declarations.
 * C, C++: in general fix intersphinx and role lookup types.
 * #8683: :confval:`html_last_updated_fmt` does not support UTC offset (%z)
 * #8683: :confval:`html_last_updated_fmt` generates wrong time zone for %Z
+* #1112: ``download`` role creates duplicated copies when relative path is
+  specified
 
 Testing
 --------
@@ -144,6 +165,10 @@ Features added
 Bugs fixed
 ----------
 
+* #8655: autodoc: Failed to generate document if target module contains an
+  object that raises an exception on ``hasattr()``
+* C, ``expr`` role should start symbol lookup in the current scope.
+
 Testing
 --------
 

doc/development/index.rst

@@ -2,10 +2,12 @@
 Extending Sphinx
 ================
 
-This guide is aimed at those wishing to develop their own extensions for
-Sphinx. Sphinx possesses significant extensibility capabilities including the
-ability to hook into almost every point of the build process.  If you simply
-wish to use Sphinx with existing extensions, refer to :doc:`/usage/index`.
+This guide is aimed at giving a quick introduction for those wishing to 
+develop their own extensions for Sphinx. Sphinx possesses significant 
+extensibility capabilities including the ability to hook into almost every
+point of the build process.  If you simply wish to use Sphinx with existing 
+extensions, refer to :doc:`/usage/index`. For a more detailed discussion of
+the extension interface see :doc:`/extdev/index`.
 
 .. toctree::
    :maxdepth: 2

doc/extdev/deprecated.rst

@@ -61,6 +61,31 @@ The following is a list of deprecated interfaces.
      - 6.0
      - ``docutils.utils.smartyquotes``
 
+   * - pending_xref node for viewcode extension
+     - 3.5
+     - 5.0
+     - ``sphinx.ext.viewcode.viewcode_anchor``
+
+   * - ``sphinx.builders.linkcheck.CheckExternalLinksBuilder.broken``
+     - 3.5
+     - 5.0
+     - N/A
+
+   * - ``sphinx.builders.linkcheck.CheckExternalLinksBuilder.good``
+     - 3.5
+     - 5.0
+     - N/A
+
+   * - ``sphinx.builders.linkcheck.CheckExternalLinksBuilder.redirected``
+     - 3.5
+     - 5.0
+     - N/A
+
+   * - ``sphinx.builders.linkcheck.node_line_or_0()``
+     - 3.5
+     - 5.0
+     - ``sphinx.util.nodes.get_node_line()``
+
    * - ``sphinx.ext.autodoc.AttributeDocumenter.isinstanceattribute()``
      - 3.5
      - 5.0
@@ -71,6 +96,16 @@ The following is a list of deprecated interfaces.
      - 5.0
      - ``sphinx.ext.autodoc.ModuleDocumenter.get_module_members()``
 
+   * - ``sphinx.ext.autosummary.generate._simple_info()``
+     - 3.5
+     - 5.0
+     - :ref:`logging-api`
+
+   * - ``sphinx.ext.autosummary.generate._simple_warn()``
+     - 3.5
+     - 5.0
+     - :ref:`logging-api`
+
    * - The ``follow_wrapped`` argument of ``sphinx.util.inspect.signature()``
      - 3.4
      - 5.0

doc/latex.rst

@@ -195,8 +195,8 @@ Keys that you may want to override include:
    "Bjornstrup".  You can also set this to ``''`` to disable fncychap.
 
    Default: ``'\\usepackage[Bjarne]{fncychap}'`` for English documents,
-       ``'\\usepackage[Sonny]{fncychap}'`` for internationalized documents, and
-       ``''`` for Japanese documents.
+   ``'\\usepackage[Sonny]{fncychap}'`` for internationalized documents, and
+   ``''`` for Japanese documents.
 
 ``'preamble'``
    Additional preamble content.  One may move all needed macros into some file
@@ -300,7 +300,7 @@ Keys that don't need to be overridden unless in special cases are:
    "inputenc" package inclusion.
 
    Default: ``'\\usepackage[utf8]{inputenc}'`` when using pdflatex, else
-       ``''``
+   ``''``
 
    .. versionchanged:: 1.4.3
       Previously ``'\\usepackage[utf8]{inputenc}'`` was used for all
@@ -389,7 +389,7 @@ Keys that don't need to be overridden unless in special cases are:
    key is ignored.
 
    Default: ``'\\usepackage{textalpha}'`` or ``''`` if ``fontenc`` does not
-       include the ``LGR`` option.
+   include the ``LGR`` option.
 
    .. versionadded:: 2.0
 
@@ -407,7 +407,7 @@ Keys that don't need to be overridden unless in special cases are:
    <latexsphinxsetup>`.
 
    Default: ``'\\usepackage{geometry}'`` (or
-       ``'\\usepackage[dvipdfm]{geometry}'`` for Japanese documents)
+   ``'\\usepackage[dvipdfm]{geometry}'`` for Japanese documents)
 
    .. versionadded:: 1.5
 
@@ -784,14 +784,14 @@ macros may be significant.
    |warningbdcolors|
        The colour for the admonition frame.
 
-       Default: ``{rgb}{0,0,0}`` (black)
+   Default: ``{rgb}{0,0,0}`` (black)
 
 .. only:: latex
 
    |wgbdcolorslatex|
        The colour for the admonition frame.
 
-       Default: ``{rgb}{0,0,0}`` (black)
+   Default: ``{rgb}{0,0,0}`` (black)
 
 |warningbgcolors|
     The background colours for the respective admonitions.

doc/usage/extensions/napoleon.rst

@@ -546,4 +546,28 @@ sure that "sphinx.ext.napoleon" is enabled in `conf.py`::
    If an attribute is documented in the docstring without a type and
    has an annotation in the class body, that type is used.
 
-   .. versionadded:: 3.4
+   .. versionadded:: 3.4
+
+.. confval:: napoleon_custom_sections
+
+   Add a list of custom sections to include, expanding the list of parsed sections.
+   *Defaults to None.*
+
+   The entries can either be strings or tuples, depending on the intention:
+
+   * To create a custom "generic" section, just pass a string.
+   * To create an alias for an existing section, pass a tuple containing the
+     alias name and the original, in that order.
+   * To create a custom section that displays like the parameters or returns
+     section, pass a tuple containing the custom section name and a string
+     value, "params_style" or "returns_style".
+
+   If an entry is just a string, it is interpreted as a header for a generic
+   section. If the entry is a tuple/list/indexed container, the first entry
+   is the name of the section, the second is the section key to emulate. If the
+   second entry value is "params_style" or "returns_style", the custom section
+   will be displayed like the parameters section or returns section.
+
+   .. versionadded:: 1.8
+   .. versionchanged:: 3.5
+      Support ``params_style`` and ``returns_style``

setup.py

@@ -44,7 +44,7 @@
     'lint': [
         'flake8>=3.5.0',
         'isort',
-        'mypy>=0.790',
+        'mypy>=0.800',
         'docutils-stubs',
     ],
     'test': [

sphinx/builders/html/__init__.py

@@ -88,7 +88,7 @@ class Stylesheet(str):
 
     def __new__(cls, filename: str, *args: str, priority: int = 500, **attributes: Any
                 ) -> "Stylesheet":
-        self = str.__new__(cls, filename)  # type: ignore
+        self = str.__new__(cls, filename)
         self.filename = filename
         self.priority = priority
         self.attributes = attributes
@@ -113,7 +113,7 @@ class JavaScript(str):
     priority = None     # type: int
 
     def __new__(cls, filename: str, priority: int = 500, **attributes: str) -> "JavaScript":
-        self = str.__new__(cls, filename)  # type: ignore
+        self = str.__new__(cls, filename)
         self.filename = filename
         self.priority = priority
         self.attributes = attributes

sphinx/builders/html/transforms.py

@@ -9,7 +9,7 @@
 """
 
 import re
-from typing import Any, Dict
+from typing import Any, Dict, List
 
 from docutils import nodes
 
@@ -38,18 +38,29 @@ class KeyboardTransform(SphinxPostTransform):
     default_priority = 400
     builders = ('html',)
     pattern = re.compile(r'(?<=.)(-|\+|\^|\s+)(?=.)')
+    multiwords_keys = (('caps', 'lock'),
+                       ('page' 'down'),
+                       ('page', 'up'),
+                       ('scroll' 'lock'),
+                       ('num', 'lock'),
+                       ('sys' 'rq'),
+                       ('back' 'space'))
 
     def run(self, **kwargs: Any) -> None:
         matcher = NodeMatcher(nodes.literal, classes=["kbd"])
         for node in self.document.traverse(matcher):  # type: nodes.literal
             parts = self.pattern.split(node[-1].astext())
-            if len(parts) == 1:
+            if len(parts) == 1 or self.is_multiwords_key(parts):
                 continue
 
             node['classes'].append('compound')
             node.pop()
             while parts:
-                key = parts.pop(0)
+                if self.is_multiwords_key(parts):
+                    key = ''.join(parts[:3])
+                    parts[:3] = []
+                else:
+                    key = parts.pop(0)
                 node += nodes.literal('', key, classes=["kbd"])
 
                 try:
@@ -59,6 +70,16 @@ def run(self, **kwargs: Any) -> None:
                 except IndexError:
                     pass
 
+    def is_multiwords_key(self, parts: List[str]) -> bool:
+        if len(parts) >= 3 and parts[1].strip() == '':
+            name = parts[0].lower(), parts[2].lower()
+            if name in self.multiwords_keys:
+                return True
+            else:
+                return False
+        else:
+            return False
+
 
 def setup(app: Sphinx) -> Dict[str, Any]:
     app.add_post_transform(KeyboardTransform)