Sphinx docs constant substitution

Question

I use Sphinx to generate documentation for my Python project. I need to describe some default values in docs. But I don't want to copy-paste the values from code to docstring because they can easily diverge later. So the question is: Is it possible to substitute a reference to constant with it's value?

I'm talking about something like this (I've made up the :py:const_value: directive):

DEFAULT = 123

class Foo:
   """Default value for something is :py:const_value:`DEFAULT`."""

And I would like to get docs like this:

Default value for something is 123.

I tried searching but I'm afraid there is no such function in Sphinx or "constant substitution" is not the right term.

If it's impossible to do with Sphinx, is there another way to avoid such duplication?

Answer 1

According to the sphinx documentation (reStructuredText Primer), the closest you can get appears to be to use substitutions, which are created using the replace:: markup. For example:

.. |PI| replace:: 3.1415

The value of PI is |PI|.

which should generate

The value of PI is 3.14159.

A possibly alternative is the python domain directive :py:const:, which inserts a link to the definition of the value, rather than substituting the actual value.