variables - 获取 Sphinx 模板中的变量

Question

我不知道如何通过模板将变量放入 Sphinx 文档中。我当然犯了一个基本错误，但是虽然有很多关于使用 Jinja/Flask 模板进行 Web 服务的文档以及 Sphinx using it 的一些文档。 ，我在执行以下操作时遇到困难。也许这是不可能的，而且我找错了树，但这与变量在 Web(而不是文档)模板中的一般工作方式有很大不同？

我正在一个更大的项目中工作。假设在我的项目的 conf.py 中我创建了一个变量，例如

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

我知道这是有效的，因为如果我使用以下行进行文档构建(我们有一个自定义文档构建，但我认为除了定制记录器和吃一堆“喋喋不休”之外，它不会做任何真正疯狂的事情) conf.py

print len(LANGS)

它会在文档构建期间显示。

但是现在我当然想在我的模板中访问这个变量。据我所知，我们用 templates/index.html 覆盖 index.rst，它继承自 Sphinx 的基本 layout.html。如果我这样做

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

我明白了

We have 0 languages

现在，这很奇怪，因为有时我可能会通过引用 undefined variable (尽管不一致)来导致构建错误，因此它以某种方式“知道”该变量已定义但认为它的长度为零。或者“空”变量的长度自动为零吗？

如何定义此变量 - 或者不可能？

我想要做的就是为列表中的每种语言做一些事情(特别是创建一个外部链接)，但我认为尝试 {% for %}/{% endfor %} 或者其他什么如果我不能让它工作。也许 Sphinx 只实现了 Jinja 的一个子集？

无论如何，请帮忙!

Answer 1

至少有两种方法可以将变量传递给模板:

1. 通过 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.

   示例:

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

2. 通过 html_theme_options 。这需要向 theme.conf 添加一个选项(您可以通过继承标准主题来创建主题):

   [options]
   num_langs = 1
   

   然后你可以通过html_theme_options在conf.py中设置num_langs:

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

   并在模板中使用它:

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