Merge branch 'master' into devel

doc/conf.py

@@ -1,5 +1,6 @@
 # Sphinx documentation build configuration file
 
+import os
 import re
 
 import sphinx
@@ -139,10 +140,33 @@ def parse_event(env, sig, signode):
     return name
 
 
+def linkify_issues_in_changelog(app, docname, source):
+    """ Linkify issue references like #123 in changelog to GitHub. """
+
+    if docname == 'changes':
+        changelog_path = os.path.join(os.path.dirname(__file__), "../CHANGES")
+        # this path trickery is needed because this script can
+        # be invoked with different working directories:
+        # * running make in docs/
+        # * running python setup.py build_sphinx in the repo root dir
+
+        with open(changelog_path) as f:
+            changelog = f.read()
+
+        def linkify(match):
+            url = 'https://github.com/sphinx-doc/sphinx/issues/' + match[1]
+            return '`{} <{}>`_'.format(match[0], url)
+
+        linkified_changelog = re.sub(r'(?:PR)?#([0-9]+)\b', linkify, changelog)
+
+        source[0] = source[0].replace('.. include:: ../CHANGES', linkified_changelog)
+
+
 def setup(app):
     from sphinx.ext.autodoc import cut_lines
     from sphinx.util.docfields import GroupedField
     app.connect('autodoc-process-docstring', cut_lines(4, what=['module']))
+    app.connect('source-read', linkify_issues_in_changelog)
     app.add_object_type('confval', 'confval',
                         objname='configuration value',
                         indextemplate='pair: %s; configuration value')

setup.py

@@ -43,7 +43,7 @@
     'lint': [
         'flake8>=3.5.0',
         'isort',
-        'mypy>=0.930',
+        'mypy>=0.931',
         'docutils-stubs',
         "types-typed-ast",
         "types-requests",

sphinx/directives/patches.py

@@ -9,7 +9,7 @@
 import os
 import warnings
 from os import path
-from typing import TYPE_CHECKING, Any, Dict, List, Tuple, cast
+from typing import TYPE_CHECKING, Any, Dict, List, Sequence, Tuple, cast
 
 from docutils import nodes
 from docutils.nodes import Node, make_id, system_message
@@ -68,7 +68,7 @@ def run(self) -> List[Node]:
 
 
 class Meta(MetaBase, SphinxDirective):
-    def run(self) -> List[Node]:
+    def run(self) -> Sequence[Node]:
         result = super().run()
         for node in result:
             # for docutils-0.17 or older.  Since docutils-0.18, patching is no longer needed
@@ -83,7 +83,7 @@ def run(self) -> List[Node]:
                 # docutils' meta nodes aren't picklable because the class is nested
                 meta.__class__ = addnodes.meta
 
-        return result  # type: ignore
+        return result
 
 
 class RSTTable(tables.RSTTable):

sphinx/locale/__init__.py

@@ -4,7 +4,7 @@
 
     Locale utilities.
 
-    :copyright: Copyright 2007-2021 by the Sphinx team, see AUTHORS.
+    :copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
     :license: BSD, see LICENSE for details.
 """
 

sphinx/util/docfields.py

@@ -21,7 +21,7 @@
 from sphinx.util.typing import TextlikeNode
 
 if TYPE_CHECKING:
-    from sphinx.directive import ObjectDescription
+    from sphinx.directives import ObjectDescription
 
 logger = logging.getLogger(__name__)
 

sphinx/util/requests.py

@@ -24,10 +24,10 @@
 except ImportError:
     try:
         # for Debian-jessie
-        from urllib3.exceptions import InsecureRequestWarning  # type: ignore
+        from urllib3.exceptions import InsecureRequestWarning
     except ImportError:
         # for requests < 2.4.0
-        InsecureRequestWarning = None  # type: ignore
+        InsecureRequestWarning = None
 
 
 useragent_header = [('User-Agent',

tests/test_domain_py.py

@@ -79,7 +79,7 @@ def assert_refnode(node, module_name, class_name, target, reftype=None,
         assert_node(node, **attributes)
 
     doctree = app.env.get_doctree('roles')
-    refnodes = list(doctree.traverse(pending_xref))
+    refnodes = list(doctree.findall(pending_xref))
     assert_refnode(refnodes[0], None, None, 'TopLevel', 'class')
     assert_refnode(refnodes[1], None, None, 'top_level', 'meth')
     assert_refnode(refnodes[2], None, 'NestedParentA', 'child_1', 'meth')
@@ -97,7 +97,7 @@ def assert_refnode(node, module_name, class_name, target, reftype=None,
     assert len(refnodes) == 13
 
     doctree = app.env.get_doctree('module')
-    refnodes = list(doctree.traverse(pending_xref))
+    refnodes = list(doctree.findall(pending_xref))
     assert_refnode(refnodes[0], 'module_a.submodule', None,
                    'ModTopLevel', 'class')
     assert_refnode(refnodes[1], 'module_a.submodule', 'ModTopLevel',
@@ -126,7 +126,7 @@ def assert_refnode(node, module_name, class_name, target, reftype=None,
     assert len(refnodes) == 16
 
     doctree = app.env.get_doctree('module_option')
-    refnodes = list(doctree.traverse(pending_xref))
+    refnodes = list(doctree.findall(pending_xref))
     print(refnodes)
     print(refnodes[0])
     print(refnodes[1])

tests/test_domain_std.py

@@ -36,7 +36,7 @@ def test_process_doc_handle_figure_caption():
         ids={'testid': figure_node},
         citation_refs={},
     )
-    document.traverse.return_value = []
+    document.findall.return_value = []
 
     domain = StandardDomain(env)
     if 'testname' in domain.data['labels']:
@@ -60,7 +60,7 @@ def test_process_doc_handle_table_title():
         ids={'testid': table_node},
         citation_refs={},
     )
-    document.traverse.return_value = []
+    document.findall.return_value = []
 
     domain = StandardDomain(env)
     if 'testname' in domain.data['labels']:

tests/test_markup.py

@@ -67,7 +67,7 @@ def parse_(rst):
         parser = RstParser()
         parser.parse(rst, document)
         SphinxSmartQuotes(document, startnode=None).apply()
-        for msg in document.traverse(nodes.system_message):
+        for msg in list(document.findall(nodes.system_message)):
             if msg['level'] == 1:
                 msg.replace_self([])
         return document

tests/test_smartquotes.py

@@ -11,6 +11,8 @@
 import pytest
 from html5lib import HTMLParser
 
+from sphinx.util import docutils
+
 
 @pytest.mark.sphinx(buildername='html', testroot='smartquotes', freshenv=True)
 def test_basic(app, status, warning):
@@ -51,7 +53,10 @@ def test_man_builder(app, status, warning):
     app.build()
 
     content = (app.outdir / 'python.1').read_text()
-    assert '\\-\\- "Sphinx" is a tool that makes it easy ...' in content
+    if docutils.__version_info__ > (0, 18):
+        assert r'\-\- \(dqSphinx\(dq is a tool that makes it easy ...' in content
+    else:
+        assert r'\-\- "Sphinx" is a tool that makes it easy ...' in content
 
 
 @pytest.mark.sphinx(buildername='latex', testroot='smartquotes', freshenv=True)

tests/test_util_nodes.py

@@ -60,31 +60,31 @@ def test_NodeMatcher():
 
     # search by node class
     matcher = NodeMatcher(nodes.paragraph)
-    assert len(list(doctree.traverse(matcher))) == 3
+    assert len(list(doctree.findall(matcher))) == 3
 
     # search by multiple node classes
     matcher = NodeMatcher(nodes.paragraph, nodes.literal_block)
-    assert len(list(doctree.traverse(matcher))) == 4
+    assert len(list(doctree.findall(matcher))) == 4
 
     # search by node attribute
     matcher = NodeMatcher(block=1)
-    assert len(list(doctree.traverse(matcher))) == 1
+    assert len(list(doctree.findall(matcher))) == 1
 
     # search by node attribute (Any)
     matcher = NodeMatcher(block=Any)
-    assert len(list(doctree.traverse(matcher))) == 3
+    assert len(list(doctree.findall(matcher))) == 3
 
     # search by both class and attribute
     matcher = NodeMatcher(nodes.paragraph, block=Any)
-    assert len(list(doctree.traverse(matcher))) == 2
+    assert len(list(doctree.findall(matcher))) == 2
 
     # mismatched
     matcher = NodeMatcher(nodes.title)
-    assert len(list(doctree.traverse(matcher))) == 0
+    assert len(list(doctree.findall(matcher))) == 0
 
     # search with Any does not match to Text node
     matcher = NodeMatcher(blah=Any)
-    assert len(list(doctree.traverse(matcher))) == 0
+    assert len(list(doctree.findall(matcher))) == 0
 
 
 @pytest.mark.parametrize(

tests/test_versioning.py

@@ -70,48 +70,48 @@ def test_picklablility():
     copy.settings.warning_stream = None
     copy.settings.env = None
     copy.settings.record_dependencies = None
-    for metanode in copy.traverse(meta):
+    for metanode in copy.findall(meta):
         metanode.__class__ = addnodes.meta
     loaded = pickle.loads(pickle.dumps(copy, pickle.HIGHEST_PROTOCOL))
-    assert all(getattr(n, 'uid', False) for n in loaded.traverse(is_paragraph))
+    assert all(getattr(n, 'uid', False) for n in loaded.findall(is_paragraph))
 
 
 def test_modified():
     modified = doctrees['modified']
     new_nodes = list(merge_doctrees(original, modified, is_paragraph))
-    uids = [n.uid for n in modified.traverse(is_paragraph)]
+    uids = [n.uid for n in modified.findall(is_paragraph)]
     assert not new_nodes
     assert original_uids == uids
 
 
 def test_added():
     added = doctrees['added']
     new_nodes = list(merge_doctrees(original, added, is_paragraph))
-    uids = [n.uid for n in added.traverse(is_paragraph)]
+    uids = [n.uid for n in added.findall(is_paragraph)]
     assert len(new_nodes) == 1
     assert original_uids == uids[:-1]
 
 
 def test_deleted():
     deleted = doctrees['deleted']
     new_nodes = list(merge_doctrees(original, deleted, is_paragraph))
-    uids = [n.uid for n in deleted.traverse(is_paragraph)]
+    uids = [n.uid for n in deleted.findall(is_paragraph)]
     assert not new_nodes
     assert original_uids[::2] == uids
 
 
 def test_deleted_end():
     deleted_end = doctrees['deleted_end']
     new_nodes = list(merge_doctrees(original, deleted_end, is_paragraph))
-    uids = [n.uid for n in deleted_end.traverse(is_paragraph)]
+    uids = [n.uid for n in deleted_end.findall(is_paragraph)]
     assert not new_nodes
     assert original_uids[:-1] == uids
 
 
 def test_insert():
     insert = doctrees['insert']
     new_nodes = list(merge_doctrees(original, insert, is_paragraph))
-    uids = [n.uid for n in insert.traverse(is_paragraph)]
+    uids = [n.uid for n in insert.findall(is_paragraph)]
     assert len(new_nodes) == 1
     assert original_uids[0] == uids[0]
     assert original_uids[1:] == uids[2:]
@@ -120,7 +120,7 @@ def test_insert():
 def test_insert_beginning():
     insert_beginning = doctrees['insert_beginning']
     new_nodes = list(merge_doctrees(original, insert_beginning, is_paragraph))
-    uids = [n.uid for n in insert_beginning.traverse(is_paragraph)]
+    uids = [n.uid for n in insert_beginning.findall(is_paragraph)]
     assert len(new_nodes) == 1
     assert len(uids) == 4
     assert original_uids == uids[1:]
@@ -130,7 +130,7 @@ def test_insert_beginning():
 def test_insert_similar():
     insert_similar = doctrees['insert_similar']
     new_nodes = list(merge_doctrees(original, insert_similar, is_paragraph))
-    uids = [n.uid for n in insert_similar.traverse(is_paragraph)]
+    uids = [n.uid for n in insert_similar.findall(is_paragraph)]
     assert len(new_nodes) == 1
     assert new_nodes[0].rawsource == 'Anyway I need more'
     assert original_uids[0] == uids[0]

tox.ini

@@ -32,9 +32,7 @@ commands=
 
 [testenv:du-latest]
 commands =
-    git clone https://repo.or.cz/docutils.git {temp_dir}/docutils
-    python -m pip install {temp_dir}/docutils/docutils
-    rm -rf {temp_dir}/docutils
+    python -m pip install "git+https://repo.or.cz/docutils.git#subdirectory=docutils"
     {[testenv]commands}
 
 [testenv:flake8]