CODEWITHSUNDEEP
pythonpython-sphinxdocstring
Derorrist
Derorrist

Reputation: 3013

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.

What am I missing here?

Python 3.4.3 BTW.

Upvotes: 1

Views: 1574

Answers (2)

aflp91
aflp91

Reputation: 673

Just using reStructuredText directive

.. include:: ./my_reusable_tip.txt

in your rst files?

Upvotes: 2

donkopotamus
donkopotamus

Reputation: 23216

In sphinx, a :ref: is simply a more robust way of linking (or referencing) another part of the document. Thus, your use of :ref: will simply provide a hyperlink to the label.

It is not a way of substituting or expanding a block.

Inline substitutions are available using using |...|, however an inline substitution cannot be used to substitute a block as you seem to require.

RestructuredText is not a template language, and thus doesn't provide macro like facilities. In the event you need it, an alternative solution is to use a template library such as mako or jinja to deal with this kind of issue.

Upvotes: 3

Related Questions