Merge branch '3.x'

.readthedocs.yml

@@ -0,0 +1,8 @@
+version: 2
+python:
+  version: 3
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs

CHANGES

@@ -70,6 +70,7 @@ Deprecated
 ----------
 
 * ``sphinx.ext.autodoc.AttributeDocumenter.isinstanceattribute()``
+* ``sphinx.ext.autodoc.directive.DocumenterBridge.reporter``
 * ``sphinx.ext.autodoc.importer.get_module_members()``
 
 Features added
@@ -87,7 +88,11 @@ Features added
 * #8649: imgconverter: Skip availability check if builder supports the image
   type
 * #6241: mathjax: Include mathjax.js only on the document using equations
+* #8651: std domain: cross-reference for a rubric having inline item is broken
 * #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
 
 Bugs fixed
 ----------
@@ -97,13 +102,21 @@ Bugs fixed
 * #8592: autodoc: ``:meta public:`` does not effect to variables
 * #8594: autodoc: empty __all__ attribute is ignored
 * #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
 * #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
+* #8665: html theme: Could not override globaltoc_maxdepth in theme.conf
 * #8094: texinfo: image files on the different directory with document are not
   copied
+* #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
 
 Testing
 --------

doc/extdev/deprecated.rst

@@ -107,6 +107,11 @@ The following is a list of deprecated interfaces.
      - 5.0
      - ``sphinx.ext.autodoc.DataDocumenter``
 
+   * - ``sphinx.ext.autodoc.directive.DocumenterBridge.reporter``
+     - 3.5
+     - 5.0
+     - ``sphinx.util.logging``
+
    * - ``sphinx.ext.autodoc.importer._getannotations()``
      - 3.4
      - 4.0

doc/usage/configuration.rst

@@ -581,12 +581,27 @@ General configuration
 
 .. confval:: highlight_options
 
-   A dictionary of options that modify how the lexer specified by
-   :confval:`highlight_language` generates highlighted source code. These are
-   lexer-specific; for the options understood by each, see the
-   `Pygments documentation <https://pygments.org/docs/lexers>`_.
+   A dictionary that maps language names to options for the lexer modules of
+   Pygments.  These are lexer-specific; for the options understood by each,
+   see the `Pygments documentation <https://pygments.org/docs/lexers>`_.
+
+   Example::
+
+     highlight_options = {
+       'default': {'stripall': True},
+       'php': {'startinline': True},
+     }
+
+   A single dictionary of options are also allowed.  Then it is recognized
+   as options to the lexer specified by :confval:`highlight_language`::
+
+     # configuration for the ``highlight_language``
+     highlight_options = {'stripall': True}
 
    .. versionadded:: 1.3
+   .. versionchanged:: 3.5
+
+      Allow to configure highlight options for multiple languages
 
 .. confval:: pygments_style
 
@@ -944,8 +959,11 @@ that use Sphinx's HTMLWriter class.
 
 .. confval:: html_baseurl
 
-   The URL which points to the root of the HTML documentation.  It is used to
-   indicate the location of document like ``canonical_url``.
+   The base URL which points to the root of the HTML documentation.  It is used
+   to indicate the location of document using `The Canonical Link Relation`_.
+   Default: ``''``.
+
+   .. _The Canonical Link Relation: https://tools.ietf.org/html/rfc6596
 
    .. versionadded:: 1.8
 

doc/usage/extensions/autodoc.rst

@@ -157,7 +157,7 @@ inserting them into the page source under a suitable :rst:dir:`py:module`,
      ``:meta private:`` in its :ref:`info-field-lists`.
      For example:
 
-     .. code-block:: rst
+     .. code-block:: python
 
         def my_function(my_arg, my_other_arg):
             """blah blah blah
@@ -172,7 +172,7 @@ inserting them into the page source under a suitable :rst:dir:`py:module`,
      an underscore.
      For example:
 
-     .. code-block:: rst
+     .. code-block:: python
 
         def _my_function(my_arg, my_other_arg):
             """blah blah blah
@@ -186,7 +186,7 @@ inserting them into the page source under a suitable :rst:dir:`py:module`,
      docstring contains ``:meta hide-value:`` in its :ref:`info-field-lists`.
      Example:
 
-     .. code-block:: rst
+     .. code-block:: python
 
         var1 = None  #: :meta hide-value:
 

doc/usage/restructuredtext/directives.rst

@@ -572,16 +572,20 @@ __ http://pygments.org/docs/lexers
       .. versionadded:: 1.3
 
    .. rst:directive:option:: dedent: number
-      :type: number
+      :type: number or no value
 
-      Strip indentation characters from the code block. For example::
+      Strip indentation characters from the code block.  When number given,
+      leading N characters are removed.  When no argument given, leading spaces
+      are removed via :func:`textwrap.dedent()`.  For example::
 
          .. code-block:: ruby
             :dedent: 4
 
                 some ruby code
 
       .. versionadded:: 1.3
+      .. versionchanged:: 3.5
+         Support automatic dedent.
 
    .. rst:directive:option:: force
       :type: no value
@@ -742,6 +746,9 @@ __ http://pygments.org/docs/lexers
    .. versionchanged:: 2.1
       Added the ``force`` option.
 
+   .. versionchanged:: 3.5
+      Support automatic dedent.
+
 .. _glossary-directive:
 
 Glossary

sphinx/config.py

@@ -362,6 +362,18 @@ def convert_source_suffix(app: "Sphinx", config: Config) -> None:
                           "But `%r' is given." % source_suffix))
 
 
+def convert_highlight_options(app: "Sphinx", config: Config) -> None:
+    """Convert old styled highlight_options to new styled one.
+
+    * old style: options
+    * new style: dict that maps language names to options
+    """
+    options = config.highlight_options
+    if options and not all(isinstance(v, dict) for v in options.values()):
+        # old styled option detected because all values are not dictionary.
+        config.highlight_options = {config.highlight_language: options}  # type: ignore
+
+
 def init_numfig_format(app: "Sphinx", config: Config) -> None:
     """Initialize :confval:`numfig_format`."""
     numfig_format = {'section': _('Section %s'),
@@ -466,6 +478,7 @@ def check_master_doc(app: "Sphinx", env: "BuildEnvironment", added: Set[str],
 
 def setup(app: "Sphinx") -> Dict[str, Any]:
     app.connect('config-inited', convert_source_suffix, priority=800)
+    app.connect('config-inited', convert_highlight_options, priority=800)
     app.connect('config-inited', init_numfig_format, priority=800)
     app.connect('config-inited', correct_copyright_year, priority=800)
     app.connect('config-inited', check_confval_types, priority=800)

sphinx/directives/code.py

@@ -7,6 +7,7 @@
 """
 
 import sys
+import textwrap
 from difflib import unified_diff
 from typing import TYPE_CHECKING, Any, Dict, List, Tuple
 
@@ -17,6 +18,7 @@
 
 from sphinx import addnodes
 from sphinx.config import Config
+from sphinx.directives import optional_int
 from sphinx.locale import __
 from sphinx.util import logging, parselinenos
 from sphinx.util.docutils import SphinxDirective
@@ -55,7 +57,7 @@ def run(self) -> List[Node]:
 
 def dedent_lines(lines: List[str], dedent: int, location: Tuple[str, int] = None) -> List[str]:
     if not dedent:
-        return lines
+        return textwrap.dedent(''.join(lines)).splitlines(True)
 
     if any(s[:dedent].strip() for s in lines):
         logger.warning(__('non-whitespace stripped by dedent'), location=location)
@@ -104,7 +106,7 @@ class CodeBlock(SphinxDirective):
     option_spec = {
         'force': directives.flag,
         'linenos': directives.flag,
-        'dedent': int,
+        'dedent': optional_int,
         'lineno-start': int,
         'emphasize-lines': directives.unchanged_required,
         'caption': directives.unchanged_required,
@@ -378,7 +380,7 @@ class LiteralInclude(SphinxDirective):
     optional_arguments = 0
     final_argument_whitespace = True
     option_spec = {
-        'dedent': int,
+        'dedent': optional_int,
         'linenos': directives.flag,
         'lineno-start': int,
         'lineno-match': directives.flag,

sphinx/domains/c.py

@@ -3657,15 +3657,18 @@ class CDomain(Domain):
     name = 'c'
     label = 'C'
     object_types = {
-        'function': ObjType(_('function'), 'func'),
-        'member': ObjType(_('member'), 'member'),
-        'macro': ObjType(_('macro'), 'macro'),
-        'type': ObjType(_('type'), 'type'),
-        'var': ObjType(_('variable'), 'data'),
-        'enum': ObjType(_('enum'), 'enum'),
-        'enumerator': ObjType(_('enumerator'), 'enumerator'),
-        'struct': ObjType(_('struct'), 'struct'),
-        'union': ObjType(_('union'), 'union'),
+        # 'identifier' is the one used for xrefs generated in signatures, not in roles
+        'member': ObjType(_('member'), 'var', 'member', 'data', 'identifier'),
+        'var': ObjType(_('variable'),  'var', 'member', 'data', 'identifier'),
+        'function': ObjType(_('function'),     'func',          'identifier', 'type'),
+        'macro': ObjType(_('macro'),           'macro',         'identifier'),
+        'struct': ObjType(_('struct'),         'struct',        'identifier', 'type'),
+        'union': ObjType(_('union'),           'union',         'identifier', 'type'),
+        'enum': ObjType(_('enum'),             'enum',          'identifier', 'type'),
+        'enumerator': ObjType(_('enumerator'), 'enumerator',    'identifier'),
+        'type': ObjType(_('type'),                              'identifier', 'type'),
+        # generated object types
+        'functionParam': ObjType(_('function parameter'),       'identifier', 'var', 'member', 'data'),  # noqa
     }
 
     directives = {

sphinx/domains/cpp.py

@@ -7251,14 +7251,18 @@ class CPPDomain(Domain):
     name = 'cpp'
     label = 'C++'
     object_types = {
-        'class':      ObjType(_('class'),      'class',             'type', 'identifier'),
-        'union':      ObjType(_('union'),      'union',             'type', 'identifier'),
-        'function':   ObjType(_('function'),   'function',  'func', 'type', 'identifier'),
-        'member':     ObjType(_('member'),     'member',    'var'),
-        'type':       ObjType(_('type'),                            'type', 'identifier'),
-        'concept':    ObjType(_('concept'),    'concept',                   'identifier'),
-        'enum':       ObjType(_('enum'),       'enum',              'type', 'identifier'),
-        'enumerator': ObjType(_('enumerator'), 'enumerator')
+        'class':      ObjType(_('class'),      'class', 'struct',   'identifier', 'type'),
+        'union':      ObjType(_('union'),      'union',             'identifier', 'type'),
+        'function':   ObjType(_('function'),   'func',              'identifier', 'type'),
+        'member':     ObjType(_('member'),     'member', 'var',     'identifier'),
+        'type':       ObjType(_('type'),                            'identifier', 'type'),
+        'concept':    ObjType(_('concept'),    'concept',           'identifier'),
+        'enum':       ObjType(_('enum'),       'enum',              'identifier', 'type'),
+        'enumerator': ObjType(_('enumerator'), 'enumerator',        'identifier'),
+        # generated object types
+        'functionParam': ObjType(_('function parameter'),           'identifier', 'member', 'var'),  # noqa
+        'templateParam': ObjType(_('template parameter'),
+                                 'identifier', 'class', 'struct', 'union', 'member', 'var', 'type'),  # noqa
     }
 
     directives = {
@@ -7435,30 +7439,19 @@ def findWarning(e: Exception) -> Tuple[str, Exception]:
 
         if typ.startswith('cpp:'):
             typ = typ[4:]
-        origTyp = typ
-        if typ == 'func':
-            typ = 'function'
-        if typ == 'struct':
-            typ = 'class'
         declTyp = s.declaration.objectType
 
         def checkType() -> bool:
-            if typ == 'any' or typ == 'identifier':
+            if typ == 'any':
                 return True
-            if declTyp == 'templateParam':
-                # TODO: perhaps this should be strengthened one day
-                return True
-            if declTyp == 'functionParam':
-                if typ == 'var' or typ == 'member':
-                    return True
             objtypes = self.objtypes_for_role(typ)
             if objtypes:
                 return declTyp in objtypes
-            print("Type is %s (originally: %s), declType is %s" % (typ, origTyp, declTyp))
+            print("Type is %s, declaration type is %s" % (typ, declTyp))
             assert False
         if not checkType():
             logger.warning("cpp:%s targets a %s (%s).",
-                           origTyp, s.declaration.objectType,
+                           typ, s.declaration.objectType,
                            s.get_full_nested_name(),
                            location=node)
 
@@ -7488,10 +7481,10 @@ def checkType() -> bool:
                     if env.config.add_function_parentheses and typ == 'any':
                         addParen += 1
                     # and now this stuff for operator()
-                    if (env.config.add_function_parentheses and typ == 'function' and
+                    if (env.config.add_function_parentheses and typ == 'func' and
                             title.endswith('operator()')):
                         addParen += 1
-                    if ((typ == 'any' or typ == 'function') and
+                    if ((typ == 'any' or typ == 'func') and
                             title.endswith('operator') and
                             displayName.endswith('operator()')):
                         addParen += 1
@@ -7500,7 +7493,7 @@ def checkType() -> bool:
                     if env.config.add_function_parentheses:
                         if typ == 'any' and displayName.endswith('()'):
                             addParen += 1
-                        elif typ == 'function':
+                        elif typ == 'func':
                             if title.endswith('()') and not displayName.endswith('()'):
                                 title = title[:-2]
                     else:

sphinx/domains/std.py

@@ -730,9 +730,11 @@ def process_doc(self, env: "BuildEnvironment", docname: str, document: nodes.doc
                                name, env.doc2path(self.labels[name][0]),
                                location=node)
             self.anonlabels[name] = docname, labelid
-            if node.tagname in ('section', 'rubric'):
+            if node.tagname == 'section':
                 title = cast(nodes.title, node[0])
                 sectname = clean_astext(title)
+            elif node.tagname == 'rubric':
+                sectname = clean_astext(node)
             elif self.is_enumerable_node(node):
                 sectname = self.get_numfig_title(node)
                 if not sectname:

sphinx/environment/adapters/toctree.py

@@ -319,8 +319,10 @@ def get_toctree_for(self, docname: str, builder: "Builder", collapse: bool,
         toctrees = []  # type: List[Element]
         if 'includehidden' not in kwargs:
             kwargs['includehidden'] = True
-        if 'maxdepth' not in kwargs:
+        if 'maxdepth' not in kwargs or not kwargs['maxdepth']:
             kwargs['maxdepth'] = 0
+        else:
+            kwargs['maxdepth'] = int(kwargs['maxdepth'])
         kwargs['collapse'] = collapse
         for toctreenode in doctree.traverse(addnodes.toctree):
             toctree = self.resolve(docname, builder, toctreenode, prune=True, **kwargs)