Get variables in Sphinx templates

Question

I can't figure out how to get variables into Sphinx documents via a template. I am certainly making an elementary mistake, but while there is lots of documentation for using Jinja/Flask templates for web service and some documentation for Sphinx using it, I am having trouble doing the following. Maybe it's not possible and I'm barking up the wrong tree, but then this is fairly different from how variables work in general in web (as opposed to doc) templates?

I am working within a much larger project. Suppose in my project's conf.py I make a variable, say

LANGS = ['en', 'de', 'cn'] 

I know that this works because if I do the docbuild (we have a custom docbuild but I don't think it does anything really crazy other than a customized logger and eating a bunch of 'chatter') with the following line in conf.py

print len(LANGS) 

it shows up during the docbuild.

But now of course I want to access this variable in my template. As far as I can tell, we override index.rst with templates/index.html, which inherits from the basic layout.html for Sphinx. And if I do

<p>We have {{ LANGS|len }} languages</p> 

I get

We have 0 languages

Now, this is weird, because sometimes I can cause an error in the build by referring to variables not defined (though not consistently), so that somehow it 'knows' that the variable is defined but thinks it has length zero. Or does a "null" variable have length zero automatically?

How do I get this variable defined - or is it not possible?

What I want to do is then do something for each language in the list (make an outside link, in particular), but I figure there is no point in trying {% for %}/{% endfor %} or whatever if I can't get this working. Maybe Sphinx implements only a subset of Jinja?

Anyway, please help!

Answer 1

There are at least two ways to pass variables to a template:

1. Via html_context:

   A dictionary of values to pass into the template engine’s context for all pages. Single values can also be put in this dictionary using the -A command-line option of sphinx-build.

   Example:

   # conf.py: html_context = {'num_langs': len(LANGS)}  <!-- template: --> <p>We have {{ num_langs }} languages</p> 

2. Via the html_theme_options. This requires adding an option to theme.conf (you can create a theme by inheriting from a standard one):

   [options] num_langs = 1 

   Then you can set num_langs in conf.py via html_theme_options:

   html_theme_options = {'num_langs': len(LANGS)} 

   and use it in a template:

   <p>We have {{ theme_num_langs }} languages</p>