sphinx-doc / sphinx-doc/sphinx

Possible bug: duplicate rST hyperlink targets don't appear to emit a warning during project processing?

Open
#13,383 16 comments 2 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

type:bug
Dominant language
Python
Stars
8k
Forks
2.6k
PR merge metrics
No merged PRs in 30d

Description

Describe the bug

This is observed from a build of the Linux kernel documentation in Arch Linux; relevant diffoscope output can be found here: https://reproducible.archlinux.org/api/v0/builds/740203/diffoscope

It seems that sometimes the hyperlink href (destination) included in the HTML output for a document may resolve to a different document, despite a local declaration of the target (in the RST source).

This is visible as a diff in the output quickly-build-trimmed-linux.html HTML file as:

│ ├── usr/lib/modules/6.13.3-arch1-1/build/Documentation/admin-guide/quickly-build-trimmed-linux.html
│ │┄ 'html2text' not available in path.
│ │ @@ -1172,15 +1172,15 @@
│ │  guide would defeat its purpose, as without such a focus you would need dozens or
│ │  hundreds of constructs along the lines of ‘in case you are having <insert
│ │  machine or distro>, you at this point have to do <this and that>
│ │  <instead|additionally>’. Each of which would make the text longer, more
│ │  complicated, and harder to follow.</p>
│ │  <p>That being said: this of course is a balancing act. Hence, if you think an
│ │  additional use-case is worth describing, suggest it to the maintainers of this
│ │ -document, as <a class="reference internal" href="#submit-improvements"><span class="std std-ref">described above</span></a>.</p>
│ │ +document, as <a class="reference internal" href="verify-bugs-and-bisect-regressions.html#submit-improvements"><span class="std std-ref">described above</span></a>.</p>
│ │  </section>
│ │  </section>
│ │  </section>
│ │  
│ │  
│ │            </div>

One characteristic of the problem link is that it is declared locally within quickly-build-trimmed-linux.rst -- but also, separately within the verify-bugs-and-bisect-regressions.rst file that the referencing link sometimes mistakenly resolves to.

I believe this problem was previously identified as one of I think three non-determinism problems reported in #6714 (we fixed one of those, another remains open, and the item I'm reporting again here seems untracked).

A workaround could be to remove the ambiguity in the kernel documentation, and that may be straightforward to do. Even so, I think this may be a bug in Sphinx.

cc @bmwiedemann
cc @kpcyrd

How to Reproduce

TBD

Environment Information
Platform:              linux; (Arch Linux; precise version TBD)
Python version:        3.13.2 (precise version TBD)
Python implementation: CPython
Sphinx version:        8.1.3
Docutils version:      0.21.2
Jinja2 version:        3.1.5
Pygments version:      2.19.1
Sphinx extensions
extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include',
              'kfigure', 'sphinx.ext.ifconfig', 'automarkup',
              'maintainers_include', 'sphinx.ext.autosectionlabel',
              'kernel_abi', 'kernel_feat', 'translations']
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

Start with the linked Linux kernel RST files, especially quickly-build-trimmed-linux.rst and verify-bugs-and-bisect-regressions.rst, using the reported Sphinx 8.1.3 environment. Reproduce the duplicate-target build and inspect the generated href and any warnings; the issue is resolved when the behavior is deterministic and duplicate targets are handled or warned about.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.