Skip to content

Fix #701 by allowing title <hyperlink>_ toctree entries#1800

Closed
dghubble wants to merge 1 commit into
sphinx-doc:masterfrom
dghubble:master
Closed

Fix #701 by allowing title <hyperlink>_ toctree entries#1800
dghubble wants to merge 1 commit into
sphinx-doc:masterfrom
dghubble:master

Conversation

@dghubble

Copy link
Copy Markdown

This PR is a stab at allowing toctree entries to contain relative links (#701) by allowing hyperlinks.

Currently, toctree's allow explicit web links via a special syntax that looks like

.. toctree::

    intro
    Some title <http://www.google.com>         <- special syntax

but replacing the explicit web link with a relative one "../some/path" results in sphinx trying to find a document and failing. Essentially, plain relative links can't be added in a toctree.

One suggestion in #701 was a special syntax <href:../some/path>. However, after looking over the code, it seems cleaner to support standard rst inline hyperlinks.

.. toctree::

    `Some title <any/link>`_
    `<title/will/be/this/link>`_

Just like inline hyperlinks in text, If no title is explicitly given, the link text is used as the title (i.e. body of the anchor tag). Separately defined .. _a link: http://example.com/ target's aren't supported though.

I'd mostly just like to see #701 addressed, whether it is this approach or something else the maintainers like.

* Hyperlink entries without a title fall back to using the ref
@dghubble dghubble changed the title Allow title <hyperlink>_ toctree entries Fix #701 by allowing title <hyperlink>_ toctree entries Mar 31, 2015
@thanatos

Copy link
Copy Markdown

👍 This did exactly what I needed. (I'm using the contrib httpdomain thing, and I need this to be able to link to http-routingtable document in the table of contents.)

@Swader

Swader commented Aug 31, 2015

Copy link
Copy Markdown

+1

@shimizukawa shimizukawa added this to the 1.4 milestone Dec 9, 2015
@tk0miya tk0miya modified the milestones: 1.5, 1.4 Feb 20, 2016
@tk0miya tk0miya modified the milestones: 1.6, 1.5 Nov 2, 2016
@tk0miya tk0miya modified the milestones: 1.7, 1.6 Apr 23, 2017
@tk0miya tk0miya modified the milestones: 1.7, 1.8 Jan 5, 2018
@tk0miya tk0miya modified the milestones: 1.8.0, 2.0 Aug 5, 2018
@dghubble dghubble closed this Aug 31, 2018
@github-actions github-actions Bot locked as resolved and limited conversation to collaborators Aug 27, 2021
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants