How can I link/reference another reST file in the documentation?

Question

I have simply no idea on how can I link to another document in the reST file.

I want to link a file named install.rst to my quickstart guide in a paragraph. I don't know how can I achieve this.

Please can you also refer to a great resource from where I can look up syntax for rest. The default quickstart is a little boring and not involves great depth discussion of using rest with sphinx.

The doc in question is : http://todx.rtfd.io

score 73 · Answer 1 · edited Sep 16 '18 at 22:05

73

To create links between different reStructuredText (.rst) files you can use the inline markup provided by sphinx. See the documentation under the heading Cross-referencing documents

on top of the file you define its label

.. _my-reference-label:

then you can link to it from other documents using

:ref:`my-reference-label`.

I do not believe you need to use the intersphinx extension, since it is for links between different projects. With this method you can link between different .rst files using their relative paths as described in the documentaion link above.

edited Sep 16 '18 at 22:05

Bruno A.

1,765
16
17

answered Apr 14 '17 at 14:10

Ryszard Cetnarski

1,952
19
20

3

When using a label, it should be `:ref:` instead of `:doc:`. With `:doc:` you would need to specify the name of the other file instead of the label. – luator Apr 17 '18 at 12:18
I strongly discourage this solution: No element except an initial comment should precede the document title because many renderers rely on this. A label at the beginning of the document might, for example, screw the navigation links of your sphinx theme. Apart from that, the answer is over-specific when the question is how to link to a doc, not to a random place in a doc. – Jeyes Unterwegs Feb 11 '21 at 23:46
The header label / target does not have to be on the top of the page. In fact you might have several in a file, for example one for each section so you can link directly to this. I do believe it is customary to place it directly before a headline (e.g. title or section header), see https://docs.readthedocs.io/en/stable/guides/cross-referencing-with-sphinx.html#explicit-targets – Sybille Peters Feb 20 '21 at 11:11
The documentation pointed to is under the section of "Cross Referencing an Arbitrary Location". Headings are already an anchor -- so you can simply reference a heading. In the example given here, simply reference the top heading, and no need to prepend the document with a reference. – SteveJ Jan 12 '22 at 22:32
@JeyesUnterwegs, do you have any specific renderer in mind that would have a problem with this? This syntax is a part of standard reStructuredText specification, and if a renderer can't deal with it properly, I'd say it's a renderer bug. – michcio1234 Jan 23 '22 at 10:53
@michcio1234 the example was mentioned in my comment: I have had this problem with a Sphinx theme, don't remember which one. That definitely was a bug. – Jeyes Unterwegs Jan 24 '22 at 11:15

score 60 · Answer 2 · answered May 29 '18 at 20:15

60

I write the link to another document using this:

:doc:`my document <../my_doc>`

../my_doc is the path to my my_doc.rst file.

I also have inter-sphinx extension in my conf.py file.

extensions = ['sphinx.ext.intersphinx']

answered May 29 '18 at 20:15

Eme Eme

832
8
9

17

Having the *intersphinx* extension is not required if you link to documents in the same project – Padix Key Sep 11 '19 at 09:51

score 34 · Answer 3 · answered Jan 10 '19 at 10:56

Simplifying @eme-eme's answer, you can just do:

:doc:`path/to/document`

You don't need to enclose the path in <> and provide a text to be displayed. In this case, a top-level header from the referenced document will be displayed as a link.

You don't need inter-sphinx extension for that.

m4sterbunny · Answer 4 · 2021-03-03T11:19:21.683

3

An existing file {example.rst} may be linked to with the following syntax:

:ref:`Optional Link text <example>`

However, pop this inside a topic or even a bullet point and behaviour may alter. So, you can refer to the final built file:

`Optional Link text <example.html>`_

Here is a great guide

edited Mar 03 '21 at 11:19

answered Feb 20 '21 at 08:08

m4sterbunny

87
1
2
8

The TYPO3 cheat sheet you linked to has some TYPO3 specific stuff which is used in rendering the docs in TYPO3-land. For example, I believe the Settings.cfg is specific. Apart from that, this is a good resource. But I would link to general restructuredText / sphinx docs, e.g. https://docs.readthedocs.io/en/stable/guides/cross-referencing-with-sphinx.html#the-ref-role If you want to link to a different manual, look for "intersphinx". – Sybille Peters Feb 20 '21 at 11:18

score 3 · Answer 5 · answered Jul 10 '21 at 15:17

3

To link from one page (.rst file) in your project to another page (different .rst file) use the following inline format:

See :ref: `topLevelHeadingofOtherPage`

For example:

See :ref:`Perform Bulk Actions`.

That's it. I agree, this information is hard to find in the Sphinx guide. It's because it's so simple I think that people assume you want to do something far more complicated.

answered Jul 10 '21 at 15:17

Simon Crum

31
2

2

I tried this. When I build, I get the error `undefined label`. – usernumber Aug 24 '21 at 13:05
Note that your first and second examples differ in the space between the ref keyword and the label. I don't believe the first example will work (at lest it doesn't in my tests, but the second one does.) – SteveJ Jan 12 '22 at 22:28

Andrey Makarov · Answer 6 · 2022-09-23T14:47:03.080

1

To reference headings one needs to add this extension to conf.py:

   extensions = [
      'sphinx.ext.autosectionlabel',
   ]

Then just use :ref:`Any heading in the project` .

See extension description for details. It can work in conjunction with Intersphinx too.

edited Sep 23 '22 at 14:47

answered Sep 14 '22 at 14:36

Andrey Makarov

46
4

Your answer could be improved with additional supporting information. Please [edit] to add further details, such as citations or documentation, so that others can confirm that your answer is correct. You can find more information on how to write good answers [in the help center](/help/how-to-answer). – Community Sep 20 '22 at 19:53
this answer works! – Shawn Zhang Jun 15 '23 at 13:54

score 1 · Answer 7 · answered Jan 23 '23 at 22:54

The suggestion by @Ryszard Cetnarski works for me, although it did take a few tries:

Relevant text from my overview.rst file:

Blah... blah...

.. _overview-database-requirements:

Database requirements
---------------------

Blah... blah...

And in the docstring of my my_python.py file:

"""Implement some more abstract base model (table) classes.

Blah... blah...

See :ref:`overview-database-requirements` for more details.
"""

I don't have to enable any additional extension.

score -9 · Accepted Answer · answered Jun 04 '16 at 14:25

-9

To referecnce other files I had to include the following in the conf.py. I took the code from the docs of Pillow(PIL fork) here.

extensions = ['sphinx.ext.intersphinx']

I think the inter-sphinx extension came to my help. It linked across the other doc pages.

answered Jun 04 '16 at 14:25

Aditya ultra

942
1
8
15

19

Would you please also describe how do you write the link to the other document? – Jindra Helcl Mar 12 '17 at 12:09

How can I link/reference another reST file in the documentation?

8 Answers8

Linked