Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Allow sections in object description directives #10919

Merged
merged 6 commits into from Oct 15, 2022
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
2 changes: 2 additions & 0 deletions CHANGES
Expand Up @@ -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
----------
Expand Down
3 changes: 2 additions & 1 deletion sphinx/directives/__init__.py
Expand Up @@ -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:
Expand Down Expand Up @@ -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)
Expand Down
Empty file.
6 changes: 6 additions & 0 deletions tests/roots/test-object-description-sections/index.rst
@@ -0,0 +1,6 @@
.. py:function:: func()

Overview
--------

Lorem ipsum dolar sit amet
45 changes: 45 additions & 0 deletions 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'