How do I output a config value in a Sphinx .rst file?

Question

I've got the following in conf.py:

def setup(app):
    app.add_config_value('base_url','http://localhost:2000', True)

How do I get this into my .rst files? I wrote this:

:base_url:/my_app/api/application/

But it only prints :base_url: instead of the actual URL.

How do I get the actual config value to be emitted?

So for the moment we did something very kludgy. We have a script that simply does a find -exec sed over the generated documents, changing the URLs in question. So it works, but... — Matt Culbreth, Apr 06 '12 at 01:58
possible duplicate of [Substitutions inside links in reST / Sphinx](http://stackoverflow.com/questions/1227037/substitutions-inside-links-in-rest-sphinx) — ideasman42, Jun 13 '15 at 13:40

score 26 · Accepted Answer · edited Jul 03 '19 at 06:53

26

For the substitution of links extlinks is fine, for including arbitrary config values as asked in your question you can use rst_epilog for substitutions (or rst_prolog for text, that should be added on top of your .rst files):

In your conf.py:

my_config_value = 42
rst_epilog = '.. |my_conf_val| replace:: %d' % my_config_value

In your .rst source:

My config value is |my_conf_val|!

In your output:

My config value is 42!

edited Jul 03 '19 at 06:53

user3079474

1,653
2
24
37

answered Apr 06 '12 at 10:11

bmu

35,119
13
91
108

Ok thanks, this has possibilities. One issue I've noticed with the extlinks is that I can't use it in the middle of a code block. It then just outputs ":api_url:" instead of the substitution. Would **rst_epilog** handle that better? – Matt Culbreth Apr 06 '12 at 10:21
I just tried it, but it doesn't work in code blocks. Maybe this is a bug in docutils, as sphinx relies on docutils substitutions here (and I think extlinks to). – bmu Apr 06 '12 at 10:33
I'll keep hacking it. Thanks for the answer. It's more general than mine so you get the vote. – Matt Culbreth Apr 06 '12 at 10:35
`%s` would probably be a better example, since it is more general and fits the question asked. – Gringo Suave Jun 23 '16 at 18:22

score 3 · Answer 2 · edited Apr 03 '20 at 17:37

3

Ah hah!

Take a look at the sphinx.ext.extlinks module.

So I have code in my conf.py that does this:

extlinks = {'api_url' : (settings.BASE_URL + '%s', settings.BASE_URL)}

And in my .rst file, I have this:

:api_url:`/myapp/api/application/`

which produces the nicely formatted link as such:

http://localhost:8000/myapp/api/application/

edited Apr 03 '20 at 17:37

bad_coder

11,289
20
44
72

answered Apr 06 '12 at 02:13

Matt Culbreth

2,835
2
19
17

score 1 · Answer 3 · answered Dec 08 '22 at 10:34

1

You can insert any conf.py existing variable in any .rst file:

conf.py:

version = "0.0.1"

rst file text:

Version: |version|

result:

answered Dec 08 '22 at 10:34

Nand0san

473
4
13

How do I output a config value in a Sphinx .rst file?

3 Answers3

Linked