Add a cross-reference to a subtitle or anchor on another page

Question

How to insert a cross-link on a reST / Sphinx page into a subheading or anchor on another page in the same documentation set?

Answer 1

Ignore this answer, it does not work: it is better to use the answer from Louis

For a binding, you can define “short” binding names as follows:

 .. _ShortAnchor: Target Header goes here ======================= Some text. 

To reference this header, use:

 For more details, see ShortAnchor_. 

Note that this even extends ShortAnchor to the full title of the header.

You can also use the full name of the header, for example:

 See `Target Header goes here`_ chapter. 

But this is more prone to errors in changing the title text.

All this works in several source files that are part of one final documentation.

Answer 2

The expression "reST / Sphinx" makes the problem unclear. Is it about reStructuredText in general and Sphinx, or just about reStructuredText, as used in Sphinx (and not in restructured text in general)? I will talk about both, as people using RST are more likely to come across both cases:

Sphinx

In addition to the directives for the domain, which can be used to communicate with various objects, such as classes ( :class: , there is a general directive :ref: documented here . They give this example:

  .. _my-reference-label: Section to cross-reference -------------------------- This is the text of the section. It refers to the section itself, see :ref:`my-reference-label`. 

Although the general hyperlink mechanism offered by RST works in Sphinx, the documentation recommends using it when using Sphinx:

Using ref is recommended for standard reStructuredText links for sections (for example, Section title _), since it works with files when section headers are changed and for all developers who support cross-references.

RST overall

Tools that convert RST files to HTML do not necessarily have a collection concept. This is, for example, if you rely on github to convert RST files to HTML, or if you use a command line tool like rst2html . Unfortunately, different ways to use the desired result depend on which tool you use. For example, if you use rst2html and want the A.rst file A.rst refer to a section named "Section" in the other.rst file and you want the latest HTML to work in the browser, then A.rst will contain:

 `This <other.html#section>`__ is a reference to a section in another file, which works with ``rst2html``. Unfortunately, it does not work when the HTML is generated through github. 

You need to link to the final HTML file, and you need to know what will be in the id for this section. If you want to do the same for a file submitted via github:

 `This <other.rst#section>`__ is a reference to a section in another file, which works on github. Unfortunately, it does not work when you use ``rst2html``. 

Here you also need to know the id given in the section. However, you are referencing the RST file because it is only when accessing the RST file that HTML code is generated. (At the time of this writing, access to HTML is directly prohibited.)

A complete example is available here .

Answer 3

The new, best answer for 2016!

The autosection extension allows you to do this easily.

 ============= Some Document ============= Internal Headline ================= 

then later ...

 =============== Some Other Doc =============== A link- :ref:`Internal Headline` 

This extension is built-in, so you only need to edit conf.py

 extensions = [ . . other . extensions . already . listed . 'sphinx.ext.autosectionlabel', ] 

The only thing you need to be careful about is that now you can’t duplicate the internal headers in the collection of documents. (Worth it.)