Merge branch '5.2.x' into 5.x

# Conflicts:
#	CHANGES
#	sphinx/__init__.py

CHANGES

@@ -19,6 +19,21 @@ Bugs fixed
 Testing
 --------
 
+Release 5.2.1 (released Sep 24, 2022)
+=====================================
+
+Bugs fixed
+----------
+
+* #10861: Always normalise the ``pycon3`` lexer to ``pycon``.
+* Fix using ``sphinx.ext.autosummary`` with modules containing titles in the
+  module-level docstring.
+
+Release 5.2.0.post0 (released Sep 24, 2022)
+===========================================
+
+* Recreated source tarballs for Debian maintainers.
+
 Release 5.2.0 (released Sep 24, 2022)
 =====================================
 
@@ -26,7 +41,7 @@ Dependencies
 ------------
 
 * #10356: Sphinx now uses declarative metadata with ``pyproject.toml`` to
-  create packages, using PyPA's ``build`` project as a build backend. Patch by
+  create packages, using PyPA's ``flit`` project as a build backend. Patch by
   Adam Turner.
 
 Deprecated

sphinx/ext/autodoc/__init__.py

@@ -961,6 +961,7 @@ class ModuleDocumenter(Documenter):
     objtype = 'module'
     content_indent = ''
     titles_allowed = True
+    _extra_indent = '   '
 
     option_spec: OptionSpec = {
         'members': members_option, 'undoc-members': bool_option,
@@ -980,7 +981,7 @@ class ModuleDocumenter(Documenter):
 
     def add_content(self, more_content: Optional[StringList]) -> None:
         old_indent = self.indent
-        self.indent += '   '
+        self.indent += self._extra_indent
         super().add_content(None)
         self.indent = old_indent
         if more_content:

sphinx/ext/autosummary/__init__.py

@@ -371,6 +371,9 @@ class Autosummary(SphinxDirective):
 
             # -- Grab the summary
 
+            # bodge for ModuleDocumenter
+            documenter._extra_indent = ''  # type: ignore[attr-defined]
+
             documenter.add_content(None)
             summary = extract_summary(self.bridge.result.data[:], self.state.document)
 

sphinx/ext/doctest.py

@@ -94,15 +94,9 @@ class TestDirective(SphinxDirective):
             # only save if it differs from code
             node['test'] = test
         if self.name == 'doctest':
-            if self.config.highlight_language in ('py', 'python'):
-                node['language'] = 'pycon'
-            else:
-                node['language'] = 'pycon3'  # default
+            node['language'] = 'pycon'
         elif self.name == 'testcode':
-            if self.config.highlight_language in ('py', 'python'):
-                node['language'] = 'python'
-            else:
-                node['language'] = 'python3'  # default
+            node['language'] = 'python'
         elif self.name == 'testoutput':
             # don't try to highlight output
             node['language'] = 'none'

sphinx/ext/viewcode.py

@@ -244,7 +244,7 @@ def collect_pages(app: Sphinx) -> Generator[Tuple[str, Dict[str, Any], str], Non
         # construct a page name for the highlighted source
         pagename = posixpath.join(OUTPUT_DIRNAME, modname.replace('.', '/'))
         # highlight the source using the builder's highlighter
-        if env.config.highlight_language in ('python3', 'default', 'none'):
+        if env.config.highlight_language in {'default', 'none'}:
             lexer = env.config.highlight_language
         else:
             lexer = 'python'

sphinx/highlighting.py

@@ -120,6 +120,8 @@ class PygmentsBridge:
                 lang = 'pycon'
             else:
                 lang = 'python'
+        if lang == 'pycon3':
+            lang = 'pycon'
 
         if lang in lexers:
             # just return custom lexers here (without installing raiseonerror filter)

sphinx/transforms/post_transforms/code.py

@@ -109,9 +109,9 @@ class TrimDoctestFlagsTransform(SphinxTransform):
             return False  # skip parsed-literal node
 
         language = node.get('language')
-        if language in ('pycon', 'pycon3'):
+        if language in {'pycon', 'pycon3'}:
             return True
-        elif language in ('py', 'py3', 'python', 'python3', 'default'):
+        elif language in {'py', 'python', 'py3', 'python3', 'default'}:
             return node.rawsource.startswith('>>>')
         elif language == 'guess':
             try:

tests/test_ext_doctest.py

@@ -29,16 +29,16 @@ def test_highlight_language_default(app, status, warning):
     app.build()
     doctree = app.env.get_doctree('doctest')
     for node in doctree.findall(nodes.literal_block):
-        assert node['language'] in ('python3', 'pycon3', 'none')
+        assert node['language'] in {'python', 'pycon', 'none'}
 
 
 @pytest.mark.sphinx('dummy', testroot='ext-doctest',
                     confoverrides={'highlight_language': 'python'})
-def test_highlight_language_python2(app, status, warning):
+def test_highlight_language_python3(app, status, warning):
     app.build()
     doctree = app.env.get_doctree('doctest')
     for node in doctree.findall(nodes.literal_block):
-        assert node['language'] in ('python', 'pycon', 'none')
+        assert node['language'] in {'python', 'pycon', 'none'}
 
 
 def test_is_allowed_version():

tests/test_highlighting.py

@@ -81,14 +81,23 @@ def test_default_highlight(logger):
     ret = bridge.highlight_block('reST ``like`` text', 'default')
     assert ret == '<div class="highlight"><pre><span></span>reST ``like`` text\n</pre></div>\n'
 
-    # python3: highlights as python3
-    ret = bridge.highlight_block('print "Hello sphinx world"', 'python3')
-    assert ret == ('<div class="highlight"><pre><span></span><span class="nb">print</span> '
-                   '<span class="s2">&quot;Hello sphinx world&quot;</span>\n</pre></div>\n')
+    # python: highlights as python3
+    ret = bridge.highlight_block('print("Hello sphinx world")', 'python')
+    assert ret == ('<div class="highlight"><pre><span></span><span class="nb">print</span>'
+                   '<span class="p">(</span>'
+                   '<span class="s2">&quot;Hello sphinx world&quot;</span>'
+                   '<span class="p">)</span>\n</pre></div>\n')
 
-    # python3: raises error if highlighting failed
-    ret = bridge.highlight_block('reST ``like`` text', 'python3')
+    # python3: highlights as python3
+    ret = bridge.highlight_block('print("Hello sphinx world")', 'python3')
+    assert ret == ('<div class="highlight"><pre><span></span><span class="nb">print</span>'
+                   '<span class="p">(</span>'
+                   '<span class="s2">&quot;Hello sphinx world&quot;</span>'
+                   '<span class="p">)</span>\n</pre></div>\n')
+
+    # python: raises error if highlighting failed
+    ret = bridge.highlight_block('reST ``like`` text', 'python')
     logger.warning.assert_called_with('Could not lex literal_block as "%s". '
-                                      'Highlighting skipped.', 'python3',
+                                      'Highlighting skipped.', 'python',
                                       type='misc', subtype='highlighting_failure',
                                       location=None)