Sphinx docs variable

Question

I'm writing documentation for a new project using Sphinx

But because this project is new, its name may change and I don't want to replace all reference of "Project Name" in all my documentation.

So I want to know if there is a way to put some variable/constant on Sphinx to do that.

I know there is a i18n feature on Sphinx, so I can use gettext to change the "Project Name" without something else. But I'm looking for a proper way to do that.

Possible duplicate of [How do I output a config value in a Sphinx .rst file?](https://stackoverflow.com/questions/10030149/how-do-i-output-a-config-value-in-a-sphinx-rst-file) — OrangeDog, Jul 29 '19 at 15:56

score 8 · Accepted Answer · edited May 23 '17 at 12:24

8

The project name is referenced by sphinx using a configuration value. The name of your project is asked if you use sphinx-quickstart to create xyour sphinx project. You can change the project name afterward by changing project in your conf.py

You can use config values in your .rst files by defining them in conf.py with rst_epilog (see this answer for an example).

edited May 23 '17 at 12:24

Community

1
1

answered Mar 01 '13 at 08:51

bmu

35,119
13
91
108

4

So in practice place this in your conf.py: `rst_epilog = '.. |project_name| replace:: %s' % project`. Then in your .rst you can simply use `|project_name|` anywhere in the text. – Pithikos May 22 '16 at 14:28
Keep in mind that if you override the value of `project` through `sphinx-build`'s `-D` command-line option, the substitution is not automatically updated. – user16785526 Oct 07 '22 at 12:32

score 7 · Answer 2 · edited Jul 29 '19 at 15:51

From the Sphinx documentation:

reST supports “substitutions” (ref), which are pieces of text and/or markup referred to in the text by |name|. They are defined like footnotes with explicit markup blocks, like this:
.. |name| replace:: replacement *text*
or this:
.. |caution| image:: warning.png
         :alt: Warning!
See the reST reference for substitutions for details.

If you want to use some substitutions for all documents, put them into rst_prolog or rst_epilog or put them into a separate file and include it into all documents you want to use them in, using the include directive. (Be sure to give the include file a file name extension differing from that of other source files, to avoid Sphinx finding it as a standalone document.)

Add your "project variable" in rst_prolog and use substitution.

Sphinx docs variable

2 Answers2