在Sphinx模板中获取变量

Question

我无法弄清楚如何通过模板将变量导入Sphinx文档.我当然犯了一个基本的错误,但是虽然有很多关于使用Jinja/Flask模板进行Web服务的文档以及使用它的Sphinx的一些文档,但我在执行以下操作时遇到了麻烦.也许这是不可能的,我正在咆哮错误的树,但这与变量在Web(而不是doc)模板中的工作方式有很大不同？

我在一个更大的项目中工作.假设在我的项目中conf.py我做了一个变量,比方说

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

我知道这是有效的,因为如果我做了docbuild(我们有一个自定义的docbuild,但我不认为除了定制的记录器以及吃了一堆'喋喋不休'之外它做了什么真的很疯狂) conf.py

print len(LANGS)

它出现在docbuild期间.

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

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

我明白了

我们有0种语言

现在,这很奇怪,因为有时我可以通过引用未定义的变量(尽管不一致)来在构建中引起错误,因此它以某种方式'知道'变量已定义但认为它的长度为零.或者"null"变量是否自动为零？

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

我想要做的就是为列表中的每种语言做一些事情(特别是制作一个外部链接),但我认为{% 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
   

   然后你可以num_langs在conf.pyvia中设置html_theme_options:

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

   并在模板中使用它:

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