CODEWITHSUNDEEP
python-sphinxrestructuredtextread-the-docs
Aditya ultra
Aditya ultra

Reputation: 992

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

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

Upvotes: 85

Views: 72504

Answers (8)

Ryszard Cetnarski
Ryszard Cetnarski

Reputation: 2052

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.

Upvotes: 78

Be Hai Nguyen
Be Hai Nguyen

Reputation: 67

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.

Upvotes: 1

Andrey Makarov
Andrey Makarov

Reputation: 124

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.

Upvotes: 3

Simon Crum
Simon Crum

Reputation: 41

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.

Upvotes: 4

m4sterbunny
m4sterbunny

Reputation: 97

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

Upvotes: 4

michcio1234
michcio1234

Reputation: 1838

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.

Upvotes: 39

Eme Eme
Eme Eme

Reputation: 900

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']

Upvotes: 65

Aditya ultra
Aditya ultra

Reputation: 992

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.

Upvotes: -9

Related Questions