sphinx-doc / sphinx-doc/sphinx
Invalid links from problematic markup.
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
To report a problem with inline markup, Docutils uses two interlinked elements:
the problematic markup is put in a <problematic> element, the related message is put in a <system_message> (below the paragraph or in a special section at the end of the document).
By default, Sphinx removes Docutils system messages from the output.
However, it leaves the <problematic> elements -- linking to non-existent system messages!
A similar problem was reported for Docutils in #435 and fixed in Docutils 0.19. See FilterMessages in docutils/transforms/universal.py.
With keep_warnings = False, some system messages are shown and the links work as expected.
However, "loose" system messages (e.g. for internal hyperlink references with unknown target) are not shown (even with keep_warnings = True). It seems the universal.Messages transform is not run.
How to Reproduce
Convert the sample document below with docutils or Sphinx's build html.
Compare the output. Try with keep_warnings = True and keep_warnings = False.
System Message Handling
***********************
Attached Messages:
Shown with ``keep_messages = True``,
filtered out with ``keep_messages = False``.
However, <problematic> content ("span.problematic") like this *asterisk
should be
* highlighted (e.g. in red), if ``keep_messages = True``,
* converted with "astext" and not link to a removed ID with
``keep_messages = False`` (cf. `transforms.universal.FilterMessages`
that also un-registers the ID).
"Loose" Messages:
are attached in a special section "System Messages" by
`transforms.universal.Messages`.
In Sphinx, they are not shown despite ``keep_messages = True``.
The "problematic" text part links to the removed system message's ID.
`link<address`_
Environment Information
Platform: linux; (Linux-6.1.0-37-amd64-x86_64-with-glibc2.36)
Python version: 3.11.2 (main, Apr 28 2025, 14:11:48) [GCC 12.2.0])
Python implementation: CPython
Sphinx version: 8.2.3
Docutils version: 0.22rc6.dev
Jinja2 version: 3.1.2
Pygments version: 2.19.1
Sphinx extensions
None.
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
Start with the sample document and compare Sphinx's HTML output under keep_warnings=True and False. Read docutils/transforms/universal.py, especially FilterMessages and Messages, then trace how Sphinx runs these transforms during build html. Done means problematic elements no longer link to removed system messages and loose messages appear consistently with the selected warning setting.
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
- Mostly clear
- Newbie friendliness
- 40/100