Skip to content

Fix section parsing in only directive - #14723

Open
Shashankrawat1504 wants to merge 1 commit into
sphinx-doc:masterfrom
Shashankrawat1504:fix/13861-only-section-parsing
Open

Shashankrawat1504 wants to merge 1 commit into
sphinx-doc:masterfrom
Shashankrawat1504:fix/13861-only-section-parsing

Conversation

@Shashankrawat1504

Copy link
Copy Markdown

Fixes #13861

Fixes incorrect section hierarchy and parser state when sections are used inside the only directive.

Previously, content inside an enabled only directive was parsed under a temporary only node and sections were reparented afterwards. This could leave Docutils' active section state inconsistent with the resulting doctree, causing subsequent sections and paragraphs to be attached to the wrong section.

This change makes only preprocess the parser input so that enabled content is parsed through the normal document parser while disabled content is blanked. This preserves the original source-line mapping and allows sections to be created in the correct document hierarchy.

Changes
Fix section hierarchy when sections occur inside only directives.
Preserve Docutils parser state while processing conditional content.
Preserve accurate source locations for warnings and errors.
Handle nested and included content correctly.
Reparse documents containing only when the active Sphinx tags change.
Track documents containing only in the build environment.
Preserve and merge only document tracking during environment merging.
Remove stale only document tracking when documents are removed.
Bump the environment version because the persistent environment data has changed.
Update affected search-index fixtures.
Add regression tests covering section hierarchy, source locations, includes, tag changes, environment handling, and merging.
Update the only directive documentation and changelog.
Testing

The following tests were run successfully:

tests/test_directives/test_directive_only.py — 17 passed
Directive, environment, and builder tests — 362 passed, 7 skipped
Internationalization tests — 61 passed
Full test suite — 2407 passed, 34 skipped, 1 xfailed
Ruff check and format check — passed
git diff --check — passed
Tested with Docutils 0.22.4 and 0.21.2

The actual process-parallel reader could not be exercised in the current Windows environment because Sphinx's process-parallel reader is platform-dependent. The environment merge behavior is covered directly by regression tests.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Problems with sections in the "only" directive.

1 participant