获取 Sphinx 模板中的变量

Question

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

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

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

我知道这是可行的，因为如果我使用以下行进行 docbuild（我们有一个自定义 docbuild，但我认为除了自定义记录器和吃一堆“喋喋不休”之外，它并没有做任何真正疯狂的事情） conf.py

print len(LANGS)

它在 docbuild 期间出现。

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

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

我明白了

我们有 0 种语言

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

如何定义这个变量 - 还是不可能？

我想要做的是然后为列表中的每种语言做一些事情（特别是做一个外部链接），但我认为尝试{% for %}/{% endfor %} 或其他任何东西都没有意义我无法让这个工作。也许 Sphinx 只实现了 Jinja 的一个子集？

无论如何，请帮忙！

Answer 1

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

1. 通过html_context：

   要传递到所有页面的模板引擎上下文中的值字典。也可以使用 sphinx-build 的 -A 命令行选项将单个值放入此字典中。

   例子：

   # 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>