Search code examples
pythonpython-sphinxdocstring

using :ref: in Python docstrings using Sphinx

I'm using Sphinx to document a python project, and I'm trying to create a reusable tip to be used in several locations.

Typically, I'll use the following syntax in a python file:

"""
.. tip::
    I want this tip to be used in several locations. Why?
        - Save time
        - Work less
"""

enter image description here

Now this works whether I put it at the beginning of the file, right under class definition or right under function definition.

I found Sphinx's manual for :ref:, which suggests to use a label:

.. _my_reusable_tip:

.. tip::
   ...

And then call this tip with :ref:`my_reusable_tip` anywhere I want. The manual states that 'it works across files, when section headings are changed, and for all builders that support cross-references'

The thing is, it doesn't matter in which .py file in the project I write the label and tip definition, the :ref:`my_reusable_tip` just displays 'my_reusable_tip', and not the tip itself.

What I'm using to build the documentation is

sphinx-apidoc -f -F -o
make html

I'm pretty sure my logic is flawed in some way, but I can't figure out why. I know that Sphinx searches the project for reStructuredText and renders it if it can, but I think I'm missing something here.

  • I tried to add this label in a seperate .py file enclosed in """, and in a separate .txt file without enclosed """.
  • I tried creating an .rst file with the label definition and rebuild the html documentation.

What am I missing here?

Python 3.4.3 BTW.

Solution

  • Just using reStructuredText directive

    .. include:: ./my_reusable_tip.txt

    in your rst files?