sphinx-doc / sphinx-doc/sphinx
"only" directive impacts subsequent anchor (not in directive content)
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 8k
- Forks
- 2.6k
- PR merge metrics
- No merged PRs in 30d
Description
Describe the bug
In my documentation project I have a tag devmode that I use in conjunction with the only directive to exclude internal developer-specific parts of the documentation for public builds. I'm using HTML as the target format.
I've encountered an issue where an anchor placed after an only directive (not within the directive content) becomes associated with a section heading inside the only directive instead of the correct one.
How to Reproduce
index.rst:
Docs
====
Section 1
---------
Some content in section 1.
.. only:: devmode
Hidden section
--------------
Some content in the hidden section.
.. _an-anchor:
Section 2
---------
More content.
Relevant part of HTML output with devmode defined:
<section id="hidden-section">
<span id="an-anchor"></span><h2>Hidden section<a class="headerlink" href="#hidden-section" title="Link to this heading">¶</a></h2>
<p>Some content in the hidden section.</p>
</section>
<section id="section-2">
<h2>Section 2<a class="headerlink" href="#section-2" title="Link to this heading">¶</a></h2>
Notice that an-anchor is associated with the heading for "Hidden section". This also means that if devmode is not defined then the anchor is not present in the output.
index.rst without only:
Docs
====
Section 1
---------
Some content in section 1.
Hidden section
--------------
Some content in the hidden section.
.. _an-anchor:
Section 2
---------
More content.
HTML output:
<section id="hidden-section">
<h2>Hidden section<a class="headerlink" href="#hidden-section" title="Link to this heading">¶</a></h2>
<p>Some content in the hidden section.</p>
</section>
<section id="section-2">
<span id="an-anchor"></span><h2>Section 2<a class="headerlink" href="#section-2" title="Link to this heading">¶</a></h2>
Note that an-anchor is now correctly associated with the heading for "Section 2".
Environment Information
Platform: win32; (Windows-11-10.0.26100-SP0)
Python version: 3.12.2 (tags/v3.12.2:6abddd9, Feb 6 2024, 21:26:36) [MSC v.1937 64 bit (AMD64)])
Python implementation: CPython
Sphinx version: 8.2.3
Docutils version: 0.21.2
Jinja2 version: 3.1.6
Pygments version: 2.19.1
Sphinx extensions
No extensions
Additional context
No response
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Reproduce the issue from the supplied index.rst example using Sphinx's HTML builder with devmode defined and then undefined. Trace the handling of the only directive and the following anchor to find why the anchor is attached to the hidden heading; done when it remains associated with Section 2 in both relevant builds.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100