Merge branch 'master' into autodoc_force_undocumented_rtype

.github/workflows/transifex.yml

@@ -15,6 +15,8 @@ jobs:
         ref: 4.x
     - name: Set up Python
       uses: actions/setup-python@v2
+      with:
+        python-version: 3.9  # https://github.com/transifex/transifex-client/pull/330
     - name: Install dependencies
       run:  pip install -U babel jinja2 transifex-client
     - name: Extract translations from source code
@@ -33,6 +35,8 @@ jobs:
         ref: 4.x
     - name: Set up Python
       uses: actions/setup-python@v2
+      with:
+        python-version: 3.9  # https://github.com/transifex/transifex-client/pull/330
     - name: Install dependencies
       run:  pip install -U babel jinja2 transifex-client
     - name: Extract translations from source code

CHANGES

@@ -7,6 +7,13 @@ Dependencies
 Incompatible changes
 --------------------
 
+* #2068: :confval:`intersphinx_disabled_reftypes` has changed default value
+  from an empty list to ``['std:doc']`` as avoid too surprising silent
+  intersphinx resolutions.
+  To migrate: either add an explicit inventory name to the references
+  intersphinx should resolve, or explicitly set the value of this configuration
+  variable to an empty list.
+
 Deprecated
 ----------
 
@@ -49,6 +56,7 @@ Incompatible changes
 Deprecated
 ----------
 
+* ``sphinx.ext.autodoc.AttributeDocumenter._datadescriptor``
 * ``sphinx.writers.html.HTMLTranslator._fieldlist_row_index``
 * ``sphinx.writers.html.HTMLTranslator._table_row_index``
 * ``sphinx.writers.html5.HTML5Translator._fieldlist_row_index``
@@ -67,6 +75,11 @@ Features added
 * #9695: More CSS classes on Javascript domain descriptions
 * #9683: Revert the removal of ``add_stylesheet()`` API.  It will be kept until
   the Sphinx-6.0 release
+* #2068, add :confval:`intersphinx_disabled_reftypes` for disabling
+  interphinx resolution of cross-references that do not have an explicit
+  inventory specification. Specific types of cross-references can be disabled,
+  e.g., ``std:doc`` or all cross-references in a specific domain,
+  e.g., ``std:*``.
 * #9792: autodoc: Add new option for ``autodoc_typehints_description_target`` to
   include undocumented return values but not undocumented parameters.
 
@@ -83,17 +96,32 @@ Bugs fixed
 * #9657: autodoc: The base class for a subclass of mocked object is incorrect
 * #9607: autodoc: Incorrect base class detection for the subclasses of the
   generic class
+* #9755: autodoc: memory addresses are shown for aliases
+* #9752: autodoc: Failed to detect type annotation for slots attribute
+* #9756: autodoc: Crashed if classmethod does not have __func__ attribute
+* #9757: autodoc: :confval:`autodoc_inherit_docstrings` does not effect to
+  overriden classmethods
 * #9630: autosummary: Failed to build summary table if :confval:`primary_domain`
   is not 'py'
 * #9670: html: Fix download file with special characters
 * #9710: html: Wrong styles for even/odd rows in nested tables
+* #9763: html: parameter name and its type annotation are not separated in HTML
 * #9649: HTML search: when objects have the same name but in different domains,
   return all of them as result instead of just one.
+* #7634: intersphinx: references on the file in sub directory are broken
+* #9737: LaTeX: hlist is rendered as a list containing "aggedright" text
 * #9678: linkcheck: file extension was shown twice in warnings
 * #9697: py domain: An index entry with parens was registered for ``py:method``
   directive with ``:property:`` option
+* #9775: py domain: Literal typehint was converted to a cross reference when
+  :confval:`autodoc_typehints='description'`
 * #9708: needs_extension failed to check double-digit version correctly
 * #9688: Fix :rst:dir:`code`` does not recognize ``:class:`` option
+* #9733: Fix for logging handler flushing warnings in the middle of the docs
+  build
+* #9656: Fix warnings without subtype being incorrectly suppressed
+* Intersphinx, for unresolved references with an explicit inventory,
+  e.g., ``proj:myFunc``, leave the inventory prefix in the unresolved text.
 
 Testing
 --------

doc/extdev/deprecated.rst

@@ -22,6 +22,11 @@ The following is a list of deprecated interfaces.
      - (will be) Removed
      - Alternatives
 
+   * - ``sphinx.ext.autodoc.AttributeDocumenter._datadescriptor``
+     - 4.3
+     - 6.0
+     - N/A
+
    * - ``sphinx.writers.html.HTMLTranslator._fieldlist_row_index``
      - 4.3
      - 6.0

doc/usage/configuration.rst

@@ -2637,10 +2637,8 @@ Options for the linkcheck builder
      A regular expression that matches a URI.
    *auth_info*
      Authentication information to use for that URI. The value can be anything
-     that is understood by the ``requests`` library (see `requests
-     Authentication <requests-auth>`_ for details).
-
-     .. _requests-auth: https://requests.readthedocs.io/en/master/user/authentication/
+     that is understood by the ``requests`` library (see :ref:`requests
+     Authentication <requests:authentication>` for details).
 
    The ``linkcheck`` builder will use the first matching ``auth_info`` value
    it can find in the :confval:`linkcheck_auth` list, so values earlier in the

doc/usage/extensions/intersphinx.rst

@@ -148,6 +148,39 @@ linking:
       exception is raised if the server has not issued a response for timeout
       seconds.
 
+.. confval:: intersphinx_disabled_reftypes
+
+   .. versionadded:: 4.3
+
+   .. versionchanged:: 5.0
+
+      Changed default value from an empty list to ``['std:doc']``.
+
+   A list of strings being either:
+
+   - the name of a specific reference type in a domain,
+     e.g., ``std:doc``, ``py:func``, or ``cpp:class``,
+   - the name of a domain, and a wildcard, e.g.,
+     ``std:*``, ``py:*``, or ``cpp:*``, or
+   - simply a wildcard ``*``.
+
+   The default value is ``['std:doc']``.
+
+   When a cross-reference without an explicit inventory specification is being
+   resolved by intersphinx, skip resolution if it matches one of the
+   specifications in this list.
+
+   For example, with ``intersphinx_disabled_reftypes = ['std:doc']``
+   a cross-reference ``:doc:`installation``` will not be attempted to be
+   resolved by intersphinx, but ``:doc:`otherbook:installation``` will be
+   attempted to be resolved in the inventory named ``otherbook`` in
+   :confval:`intersphinx_mapping`.
+   At the same time, all cross-references generated in, e.g., Python,
+   declarations will still be attempted to be resolved by intersphinx.
+
+   If ``*`` is in the list of domains, then no references without an explicit
+   inventory will be resolved by intersphinx.
+
 
 Showing all links of an Intersphinx mapping file
 ------------------------------------------------

doc/usage/installation.rst

@@ -120,7 +120,7 @@ Chocolatey
    $ choco install sphinx
    
 You would need to `install Chocolatey
-<https://chocolatey.org/install/>`_
+<https://chocolatey.org/install>`_
 before running this.
 
 For more information, refer to the `chocolatey page`__.

sphinx/builders/_epub_base.py

@@ -323,14 +323,14 @@ def footnote_spot(tree: nodes.document) -> Tuple[Element, int]:
             # a) place them after the last existing footnote
             # b) place them after an (empty) Footnotes rubric
             # c) create an empty Footnotes rubric at the end of the document
-            fns = tree.traverse(nodes.footnote)
+            fns = list(tree.traverse(nodes.footnote))
             if fns:
                 fn = fns[-1]
                 return fn.parent, fn.parent.index(fn) + 1
             for node in tree.traverse(nodes.rubric):
                 if len(node) == 1 and node.astext() == FOOTNOTES_RUBRIC_NAME:
                     return node.parent, node.parent.index(node) + 1
-            doc = tree.traverse(nodes.document)[0]
+            doc = list(tree.traverse(nodes.document))[0]
             rub = nodes.rubric()
             rub.append(nodes.Text(FOOTNOTES_RUBRIC_NAME))
             doc.append(rub)
@@ -339,10 +339,10 @@ def footnote_spot(tree: nodes.document) -> Tuple[Element, int]:
         if show_urls == 'no':
             return
         if show_urls == 'footnote':
-            doc = tree.traverse(nodes.document)[0]
+            doc = list(tree.traverse(nodes.document))[0]
             fn_spot, fn_idx = footnote_spot(tree)
             nr = 1
-        for node in tree.traverse(nodes.reference):
+        for node in list(tree.traverse(nodes.reference)):
             uri = node.get('refuri', '')
             if (uri.startswith('http:') or uri.startswith('https:') or
                     uri.startswith('ftp:')) and uri not in node.astext():

sphinx/builders/latex/transforms.py

@@ -45,7 +45,7 @@ class SubstitutionDefinitionsRemover(SphinxPostTransform):
     formats = ('latex',)
 
     def run(self, **kwargs: Any) -> None:
-        for node in self.document.traverse(nodes.substitution_definition):
+        for node in list(self.document.traverse(nodes.substitution_definition)):
             node.parent.remove(node)
 
 
@@ -81,7 +81,7 @@ def expand_show_urls(self) -> None:
         if show_urls is False or show_urls == 'no':
             return
 
-        for node in self.document.traverse(nodes.reference):
+        for node in list(self.document.traverse(nodes.reference)):
             uri = node.get('refuri', '')
             if uri.startswith(URI_SCHEMES):
                 if uri.startswith('mailto:'):
@@ -501,7 +501,7 @@ class BibliographyTransform(SphinxPostTransform):
 
     def run(self, **kwargs: Any) -> None:
         citations = thebibliography()
-        for node in self.document.traverse(nodes.citation):
+        for node in list(self.document.traverse(nodes.citation)):
             node.parent.remove(node)
             citations += node
 
@@ -602,9 +602,9 @@ class IndexInSectionTitleTransform(SphinxPostTransform):
     formats = ('latex',)
 
     def run(self, **kwargs: Any) -> None:
-        for node in self.document.traverse(nodes.title):
+        for node in list(self.document.traverse(nodes.title)):
             if isinstance(node.parent, nodes.section):
-                for i, index in enumerate(node.traverse(addnodes.index)):
+                for i, index in enumerate(list(node.traverse(addnodes.index))):
                     # move the index node next to the section title
                     node.remove(index)
                     node.parent.insert(i + 1, index)

sphinx/domains/c.py

@@ -92,7 +92,7 @@
 _string_re = re.compile(r"[LuU8]?('([^'\\]*(?:\\.[^'\\]*)*)'"
                         r'|"([^"\\]*(?:\\.[^"\\]*)*)")', re.S)
 
-_simple_type_sepcifiers_re = re.compile(r"""(?x)
+_simple_type_specifiers_re = re.compile(r"""(?x)
     \b(
     void|_Bool|bool
     # Integer
@@ -2584,7 +2584,7 @@ def _parse_trailing_type_spec(self) -> ASTTrailingTypeSpec:
         # fundamental types, https://en.cppreference.com/w/c/language/type
         # and extensions
         self.skip_ws()
-        if self.match(_simple_type_sepcifiers_re):
+        if self.match(_simple_type_specifiers_re):
             return ASTTrailingTypeSpecFundamental(self.matched_text)
 
         # prefixed

sphinx/domains/cpp.py

@@ -335,7 +335,7 @@
 ]
 
 
-_simple_type_sepcifiers_re = re.compile(r"""(?x)
+_simple_type_specifiers_re = re.compile(r"""(?x)
     \b(
     auto|void|bool
     # Integer
@@ -5859,7 +5859,7 @@ def _parse_trailing_type_spec(self) -> ASTTrailingTypeSpec:
         # fundamental types, https://en.cppreference.com/w/cpp/language/type
         # and extensions
         self.skip_ws()
-        if self.match(_simple_type_sepcifiers_re):
+        if self.match(_simple_type_specifiers_re):
             return ASTTrailingTypeSpecFundamental(self.matched_text)
 
         # decltype

sphinx/domains/index.py

@@ -48,7 +48,7 @@ def merge_domaindata(self, docnames: Iterable[str], otherdata: Dict) -> None:
     def process_doc(self, env: BuildEnvironment, docname: str, document: Node) -> None:
         """Process a document after it is read by the environment."""
         entries = self.entries.setdefault(env.docname, [])
-        for node in document.traverse(addnodes.index):
+        for node in list(document.traverse(addnodes.index)):
             try:
                 for entry in node['entries']:
                     split_index_msg(entry[0], entry[1])

sphinx/domains/python.py

@@ -328,7 +328,7 @@ def make_xref(self, rolename: str, domain: str, target: str,
                 text = target[1:]
             elif prefix == '~':
                 text = target.split('.')[-1]
-            for node in result.traverse(nodes.Text):
+            for node in list(result.traverse(nodes.Text)):
                 node.parent[node.parent.index(node)] = nodes.Text(text)
                 break
         elif isinstance(result, pending_xref) and env.config.python_use_unqualified_type_names:
@@ -353,17 +353,21 @@ def make_xrefs(self, rolename: str, domain: str, target: str,
 
         split_contnode = bool(contnode and contnode.astext() == target)
 
+        in_literal = False
         results = []
         for sub_target in filter(None, sub_targets):
             if split_contnode:
                 contnode = nodes.Text(sub_target)
 
-            if delims_re.match(sub_target):
+            if in_literal or delims_re.match(sub_target):
                 results.append(contnode or innernode(sub_target, sub_target))
             else:
                 results.append(self.make_xref(rolename, domain, sub_target,
                                               innernode, contnode, env, inliner, location))
 
+            if sub_target in ('Literal', 'typing.Literal'):
+                in_literal = True
+
         return results
 
 

sphinx/environment/__init__.py

@@ -45,6 +45,7 @@
 logger = logging.getLogger(__name__)
 
 default_settings: Dict[str, Any] = {
+    'auto_id_prefix': 'id',
     'embed_images': False,
     'embed_stylesheet': False,
     'cloak_email_addresses': True,

sphinx/environment/adapters/toctree.py

@@ -193,13 +193,13 @@ def _entries_from_toctree(toctreenode: addnodes.toctree, parents: List[str],
                         for toplevel in children:
                             # nodes with length 1 don't have any children anyway
                             if len(toplevel) > 1:
-                                subtrees = toplevel.traverse(addnodes.toctree)
+                                subtrees = list(toplevel.traverse(addnodes.toctree))
                                 if subtrees:
                                     toplevel[1][:] = subtrees  # type: ignore
                                 else:
                                     toplevel.pop(1)
                     # resolve all sub-toctrees
-                    for subtocnode in toc.traverse(addnodes.toctree):
+                    for subtocnode in list(toc.traverse(addnodes.toctree)):
                         if not (subtocnode.get('hidden', False) and
                                 not includehidden):
                             i = subtocnode.parent.index(subtocnode) + 1

sphinx/environment/collectors/metadata.py

@@ -33,9 +33,12 @@ def process_doc(self, app: Sphinx, doctree: nodes.document) -> None:
 
         Keep processing minimal -- just return what docutils says.
         """
-        if len(doctree) > 0 and isinstance(doctree[0], nodes.docinfo):
+        index = doctree.first_child_not_matching_class(nodes.PreBibliographic)
+        if index is None:
+            return
+        elif isinstance(doctree[index], nodes.docinfo):
             md = app.env.metadata[app.env.docname]
-            for node in doctree[0]:
+            for node in doctree[index]:  # type: ignore
                 # nodes are multiply inherited...
                 if isinstance(node, nodes.authors):
                     authors = cast(List[nodes.author], node)
@@ -58,7 +61,7 @@ def process_doc(self, app: Sphinx, doctree: nodes.document) -> None:
                         value = 0
                     md[name] = value
 
-            doctree.pop(0)
+            doctree.pop(index)
 
 
 def setup(app: Sphinx) -> Dict[str, Any]:

sphinx/ext/autodoc/__init__.py

@@ -2329,12 +2329,11 @@ def import_object(self, raiseerror: bool = False) -> bool:
 
         return ret
 
-    def should_suppress_directive_header(self) -> bool:
+    def should_suppress_value_header(self) -> bool:
         if self.object is SLOTSATTR:
-            self._datadescriptor = True
             return True
         else:
-            return super().should_suppress_directive_header()
+            return super().should_suppress_value_header()
 
     def get_doc(self, ignore: int = None) -> Optional[List[List[str]]]:
         if self.object is SLOTSATTR:
@@ -2352,6 +2351,15 @@ def get_doc(self, ignore: int = None) -> Optional[List[List[str]]]:
         else:
             return super().get_doc(ignore)  # type: ignore
 
+    @property
+    def _datadescriptor(self) -> bool:
+        warnings.warn('AttributeDocumenter._datadescriptor() is deprecated.',
+                      RemovedInSphinx60Warning)
+        if self.object is SLOTSATTR:
+            return True
+        else:
+            return False
+
 
 class RuntimeInstanceAttributeMixin(DataDocumenterMixinBase):
     """

sphinx/ext/autosummary/__init__.py

@@ -583,7 +583,7 @@ def parse(doc: List[str], settings: Any) -> nodes.document:
                 node = parse(doc, document.settings)
                 if summary.endswith(WELL_KNOWN_ABBREVIATIONS):
                     pass
-                elif not node.traverse(nodes.system_message):
+                elif not list(node.traverse(nodes.system_message)):
                     # considered as that splitting by period does not break inline markups
                     break