IntenseWebs/sphinx
3
0
Fork 0
mirror of https://github.com/sphinx-doc/sphinx.git synced 2025-02-25 18:55:22 -06:00
Code Issues Packages Projects Releases Wiki Activity
2c83af0aab
sphinx/tests/test_directive_object_description.py

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

60 lines
2.0 KiB
Python
Raw Normal View History

Allow sections in object description directives (#10919)
2022-10-15 17:01:25 -05:00
"""Test object description directives."""
Add ``content_offset`` parameter to ``nested_parse_with_titles`` (#11147) Previously, ``nested_parse_with_titles`` always passed ``0`` as the input offset when invoking ``nested_parse``. When parsing the content of a directive, as is a common use case for ``nested_parse_with_titles``, this leads to incorrect source file/line number information, as it does not take into account the directive's ``content_offset``, which is always non-zero. This issue affects *all* object descriptions due to GH-10887. It also affects the ``sphinx.ext.ifconfig`` extension. The ``py:module`` and ``js:module`` directives employed a workaround for this issue, by wrapping the calls to ``nested_parse_with_title`` with ``switch_source_input``. That worked, but was more complicated (and likely less efficient) than necessary. This commit adds an optional ``content_offset`` parameter to ``nested_parse_with_titles``, and fixes callers to pass the appropriate content offset when needed. This commit eliminates the now-unnecessary calls to ``switch_source_input`` and instead specifies the correct ``content_offset``.
2023-02-14 23:45:28 -06:00
import docutils.utils
Allow sections in object description directives (#10919)
2022-10-15 17:01:25 -05:00
import pytest
from docutils import nodes
from sphinx import addnodes
from sphinx.io import create_publisher
Add ``content_offset`` parameter to ``nested_parse_with_titles`` (#11147) Previously, ``nested_parse_with_titles`` always passed ``0`` as the input offset when invoking ``nested_parse``. When parsing the content of a directive, as is a common use case for ``nested_parse_with_titles``, this leads to incorrect source file/line number information, as it does not take into account the directive's ``content_offset``, which is always non-zero. This issue affects *all* object descriptions due to GH-10887. It also affects the ``sphinx.ext.ifconfig`` extension. The ``py:module`` and ``js:module`` directives employed a workaround for this issue, by wrapping the calls to ``nested_parse_with_title`` with ``switch_source_input``. That worked, but was more complicated (and likely less efficient) than necessary. This commit adds an optional ``content_offset`` parameter to ``nested_parse_with_titles``, and fixes callers to pass the appropriate content offset when needed. This commit eliminates the now-unnecessary calls to ``switch_source_input`` and instead specifies the correct ``content_offset``.
2023-02-14 23:45:28 -06:00
from sphinx.testing import restructuredtext
Allow sections in object description directives (#10919)
2022-10-15 17:01:25 -05:00
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'
Add ``content_offset`` parameter to ``nested_parse_with_titles`` (#11147) Previously, ``nested_parse_with_titles`` always passed ``0`` as the input offset when invoking ``nested_parse``. When parsing the content of a directive, as is a common use case for ``nested_parse_with_titles``, this leads to incorrect source file/line number information, as it does not take into account the directive's ``content_offset``, which is always non-zero. This issue affects *all* object descriptions due to GH-10887. It also affects the ``sphinx.ext.ifconfig`` extension. The ``py:module`` and ``js:module`` directives employed a workaround for this issue, by wrapping the calls to ``nested_parse_with_title`` with ``switch_source_input``. That worked, but was more complicated (and likely less efficient) than necessary. This commit adds an optional ``content_offset`` parameter to ``nested_parse_with_titles``, and fixes callers to pass the appropriate content offset when needed. This commit eliminates the now-unnecessary calls to ``switch_source_input`` and instead specifies the correct ``content_offset``.
2023-02-14 23:45:28 -06:00
def test_object_description_content_line_number(app):
text = (".. py:function:: foo(bar)\n" +
"\n" +
" Some link here: :ref:`abc`\n")
doc = restructuredtext.parse(app, text)
xrefs = list(doc.findall(condition=addnodes.pending_xref))
assert len(xrefs) == 1
source, line = docutils.utils.get_source_line(xrefs[0])
assert 'index.rst' in source
assert line == 3
Reference in New Issue Copy Permalink