CODEWITHSUNDEEP
python-sphinx
NOhs
NOhs

Reputation: 2830

How to reference an *.rst file from the docstring of a module using sphinx

I wrote a little tutorial in rst format. Now for the documentation generated by apidoc, I would like to reference that tutorial in the docstring using:

:any:`<my_tut>`

Where my_tut.rst is in the top level directory of my Sphinx-documentation source-folder. However, I get the error

WARNING: 'any' reference target not found: my_tut

Added info:

The output of apidoc is not in the toplevel source folder, but in a subfolder called code.

Upvotes: 3

Views: 1292

Answers (1)

mzjn
mzjn

Reputation: 50957

The :doc: role can be used to create a cross-reference to my_tut.rst:

:doc:`my_tut`

If the link source and the link target are in different folders, that needs to be taken into account. With a target one level above the source, it would look like this:

:doc:`../my_tut`

An alternative is to add a label immediately before the relevant heading in my_tut.rst and use that as the cross-reference target. If the label definition is .. _my_label:, you would reference it like this:

:any:`my_label`

You could also use :ref:`my_label`.

Upvotes: 4

Related Questions