sphinx-doc / sphinx-doc/sphinx

"only" directive impacts subsequent anchor (not in directive content)

Open
#13,484 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

directives:only type:bug
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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.