Allow sections in object description directives (#10919)

CHANGES

@@ -21,6 +21,8 @@ Features added
   Patch by Martin Liska.
 * #10881: autosectionlabel: Record the generated section label to the debug log.
 * #10268: Correctly URI-escape image filenames.
+* #10887: domains: Allow sections in all the content of all object description
+  directives (e.g. :rst:dir:`py:function`). Patch by Adam Turner
 
 Bugs fixed
 ----------

sphinx/directives/__init__.py

@@ -12,6 +12,7 @@
 from sphinx.util import docutils
 from sphinx.util.docfields import DocFieldTransformer, Field, TypedField
 from sphinx.util.docutils import SphinxDirective
+from sphinx.util.nodes import nested_parse_with_titles
 from sphinx.util.typing import OptionSpec
 
 if TYPE_CHECKING:
@@ -259,7 +260,7 @@ def run(self) -> List[Node]:
             # needed for association of version{added,changed} directives
             self.env.temp_data['object'] = self.names[0]
         self.before_content()
-        self.state.nested_parse(self.content, self.content_offset, contentnode)
+        nested_parse_with_titles(self.state, self.content, contentnode)
         self.transform_content(contentnode)
         self.env.app.emit('object-description-transform',
                           self.domain, self.objtype, contentnode)

tests/roots/test-object-description-sections/index.rst

@@ -0,0 +1,6 @@
+.. py:function:: func()
+
+   Overview
+   --------
+
+   Lorem ipsum dolar sit amet

tests/test_directive_object_description.py

@@ -0,0 +1,45 @@
+"""Test object description directives."""
+
+import pytest
+from docutils import nodes
+
+from sphinx import addnodes
+from sphinx.io import create_publisher
+from sphinx.util.docutils import sphinx_domains
+
+
+def _doctree_for_test(builder, docname: str) -> nodes.document:
+    builder.env.prepare_settings(docname)
+    publisher = create_publisher(builder.app, 'restructuredtext')
+    with sphinx_domains(builder.env):
+        publisher.set_source(source_path=builder.env.doc2path(docname))
+        publisher.publish()
+        return publisher.document
+
+
+@pytest.mark.sphinx('text', testroot='object-description-sections')
+def test_object_description_sections(app):
+    doctree = _doctree_for_test(app.builder, 'index')
+    # <document>
+    #     <index>
+    #     <desc>
+    #         <desc_signature>
+    #             <desc_name>
+    #                 func
+    #             <desc_parameterlist>
+    #         <desc_content>
+    #             <section>
+    #                 <title>
+    #                     Overview
+    #                 <paragraph>
+    #                     Lorem ipsum dolar sit amet
+
+    assert isinstance(doctree[0], addnodes.index)
+    assert isinstance(doctree[1], addnodes.desc)
+    assert isinstance(doctree[1][0], addnodes.desc_signature)
+    assert isinstance(doctree[1][1], addnodes.desc_content)
+    assert isinstance(doctree[1][1][0], nodes.section)
+    assert isinstance(doctree[1][1][0][0], nodes.title)
+    assert doctree[1][1][0][0][0] == 'Overview'
+    assert isinstance(doctree[1][1][0][1], nodes.paragraph)
+    assert doctree[1][1][0][1][0] == 'Lorem ipsum dolar sit amet'