diff --git a/CHANGES b/CHANGES index 4df27fbbfa3..511e3eff36b 100644 --- a/CHANGES +++ b/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 ---------- diff --git a/sphinx/directives/__init__.py b/sphinx/directives/__init__.py index e59cb1295d8..8fcbd1fffd6 100644 --- a/sphinx/directives/__init__.py +++ b/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) diff --git a/tests/roots/test-object-description-sections/conf.py b/tests/roots/test-object-description-sections/conf.py new file mode 100644 index 00000000000..e69de29bb2d diff --git a/tests/roots/test-object-description-sections/index.rst b/tests/roots/test-object-description-sections/index.rst new file mode 100644 index 00000000000..1892f94d6e4 --- /dev/null +++ b/tests/roots/test-object-description-sections/index.rst @@ -0,0 +1,6 @@ +.. py:function:: func() + + Overview + -------- + + Lorem ipsum dolar sit amet diff --git a/tests/test_directive_object_description.py b/tests/test_directive_object_description.py new file mode 100644 index 00000000000..e161d5401bd --- /dev/null +++ b/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') + # + # + # + # + # + # func + # + # + #
+ # + # 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'