sphinx-doc / sphinx-doc/sphinx
Parse reference titles as reStructuredText
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 8k
- Forks
- 2.6k
- PR merge metrics
- No merged PRs in 30d
Description
Feature Suggestion
Parse the reference title text with self.state.inline_text in the sphinx.ReferenceRole
(the same approach used, for example, by admonition titles, rubric titles, table titles and parsed-literal role)
Description
In sphinx rST, if you write :ref:`*title* <ref>` , *title* is interpreted as literal text and translated to a literal node: https://github.com/sphinx-doc/sphinx/blob/697dff31ab09625ead62e1a7ec0780126aeb07c6/sphinx/roles.py#L77
This IMO is not ideal and there are many use cases where one would expect the text to be parsed as rST.
In MyST-Parser, I have overriden some of the reference processing code (see here), such that nested syntax is parsed as "expected".
For example the following Markdown is parsed correctly by Markdown parsers:
[This is a title with nested __*bold italic*__ syntax](ref)
This is a title with nested bold italic syntax
and now is also correctly parsed into docutils AST, before post-transforms:
<document source="root/index.md">
<paragraph>
<pending_xref refdomain="True" refexplicit="True" reftarget="ref" reftype="myst" refwarn="True">
<inline classes="xref myst">
This is a title with nested
<strong>
<emphasis>
bold italic
syntax
and after post-transforms:
<document source="root/index.md">
<paragraph>
<reference internal="True" refid="ref">
<inline classes="std std-ref">
This is a title with nested
<strong>
<emphasis>
bold italic
syntax
If there is interest in this, I would consider spending some time writing up a PR to upstream some of these alterations.
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 in sphinx/roles.py at ReferenceRole and inspect its use of self.state.inline_text alongside the analogous title-handling roles mentioned in the issue. Confirm the expected docutils AST for nested reStructuredText in a reference title, then add or update coverage so the title is parsed rather than treated as literal text.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- markdown, python
- Domain
- documentation
- Issue type
- Feature
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 38/100