sphinx-doc / sphinx-doc/sphinx

Misleading documentation on rST hyperlink syntax.

Open
#13,613 12 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

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

Description

Describe the bug

The reStructuredText Primer (doc/usage/restructuredtext/basics.rst) starts the section on External links with

Use ```Link text <https://domain.invalid/>`_`` for inline web links. 

which is, according to the reStructuredText Markup Specification the syntax for a "named hyperlink reference with embedded URI", the most complex and most misunderstood link syntax variant.

Users thus primed will be surprised when a subsequent "inline link" with the same link text results in a WARNING Duplicate explicit target name: "link text" because the syntax is equivalent to the link–target pair ("reference link")

Use ```Link text`_`` for hyperlinks. Add a target block::

    .. _link text: https://domain.invalid/

at a suitable place.

and generates two Doctree elements:

<reference name="Link text" refuri="https://domain.invalid/">Link text</reference>
<target ids="link-text" names="link\ text" refuri="https://domain.invalid/"></target>

The rST analogon to Markup "inline links" is an "anonymous hyperlink reference with embedded URI/alias" which uses a double trailing underline.

There is actually no good reason to use a named link with embedded href
(with single trailing underline):

  • If the established reference name is used at several places, a separate named target adds clarity.

  • One-off use cases are better served with the anonymous variant (with double trailing underline) or an "normal" anonymous reference – target pair.

Suggestion:

  • Start the "primer" documentation section with "reference links". In rST, they are easier than "inline links".
  • For "inline links", write
    Use ```Link text <https://domain.invalid/>`__`` for inline web links 
    (**mind the double underline at the end**, for details see the `rST specification`__).
    
    __ https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#embedded-uris-and-aliases`__
    
How to Reproduce

index.rst:

The references `link text <https://domain.invalid/>`_
and `link text <https://example.com/>`_ generate a warning.
Environment Information

The bug is in the current online documentation
https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#external-links

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

Read doc/usage/restructuredtext/basics.rst and reproduce the duplicate-target warning with the issue's index.rst example. Update the External links section to distinguish reference links from anonymous embedded-URI links, then verify the documentation no longer recommends the misleading single-underline syntax.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Clearly specified
Newbie friendliness
52/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.