Opened 2 years ago

Closed 2 years ago

#30444 closed enhancement (fixed)

Mention anonymous hyperlinks in developer doc

Reported by: Sébastien Labbé Owned by:
Priority: major Milestone: sage-9.2
Component: documentation Keywords:
Cc: Merged in:
Authors: Sébastien Labbé Reviewers: Marc Mezzarobba, Matthias Koeppe
Report Upstream: N/A Work issues:
Branch: f3ecbf2 (Commits, GitHub, GitLab) Commit: f3ecbf2a149bc3fca47cf442ffc384bab3098e27
Dependencies: Stopgaps:

Status badges

Description (last modified by Sébastien Labbé)

In the documentation of a sage file, writing

see `this page <http://www.example1.com>`_
or `this page <http://www.example2.com>`_

creates an error while building the documentation saying WARNING: Duplicate explicit target name: "this page".

One solution is to use anonymous hyperlinks with double underscores as in:

see `this page <http://www.example1.com>`__
or `this page <http://www.example2.com>`__

See: Restructured text (rst) http links underscore ('__' vs '_' use) on stackoverflow.

This ticket aims to add documentation about that solution in the section on Hyperlinks of the sage manual.

The issue was raised in #30393, in particular see comment:22.

Change History (8)

comment:1 Changed 2 years ago by Sébastien Labbé

Authors: Sébastien Labbé
Branch: u/slabbe/30444
Commit: f3ecbf2a149bc3fca47cf442ffc384bab3098e27
Status: newneeds_review

New commits:

9b9b278add anonymous hyperlinks to developper documentation
f3ecbf2small fix

comment:2 Changed 2 years ago by Sébastien Labbé

Description: modified (diff)

comment:3 Changed 2 years ago by Sébastien Labbé

Description: modified (diff)

comment:4 Changed 2 years ago by Sébastien Labbé

Description: modified (diff)

comment:5 Changed 2 years ago by Marc Mezzarobba

I would just modify the existing sentence to say

If you want a specific link name, use ```link name <http://www.example.com>`__`` (with two underscores at the end)

but I'm okay with your version too.

Also, I'm not sure how idiomatic “creates an error” is, but your English is likely better than mine!

comment:6 Changed 2 years ago by Sébastien Labbé

I agree, the new paragraph was too long. Will do the update next week (going on vacation tomorrow).

comment:7 Changed 2 years ago by Matthias Köppe

Reviewers: Marc Mezzarobba, Matthias Koeppe
Status: needs_reviewpositive_review

It's an improvement already and further refinements can also be done in a follow up ticket.

comment:8 Changed 2 years ago by Volker Braun

Branch: u/slabbe/30444f3ecbf2a149bc3fca47cf442ffc384bab3098e27
Resolution: fixed
Status: positive_reviewclosed
Note: See TracTickets for help on using tickets.