Получить переменные в шаблонах Sphinx

Я не могу понять, как получить переменные в документы Sphinx через шаблон. Я, конечно, делаю элементарную ошибку, но пока есть много документации для использования шаблонов Jinja/Flask для веб-сервиса и некоторой документации для Sphinx, использующей ее, у меня возникают проблемы делая следующее. Возможно, это невозможно, и я лаю неправильное дерево, но тогда это довольно отличается от того, как переменные работают вообще в веб-шаблонах (в отличие от doc)?

Я работаю в гораздо более крупном проекте. Предположим, что в моем проекте conf.py я делаю переменную, скажем

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

Я знаю, что это работает, потому что, если я делаю docbuild (у нас есть пользовательский docbuild, но я не думаю, что он делает что-то действительно сумасшедшее, кроме настраиваемого регистратора, и есть кучу "болтовни" ) со следующей строкой в conf.py

print len(LANGS)

он появляется во время docbuild.

Но теперь, конечно, я хочу получить доступ к этой переменной в моем шаблоне. Насколько я могу судить, мы переопределяем index.rst с помощью templates/index.html, который наследуется от основного layout.html для Sphinx. И если я делаю

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

Я получаю

У нас есть 0 языков

Теперь это странно, потому что иногда я могу вызвать ошибку в сборке, ссылаясь на переменные, которые не определены (хотя и не последовательно), так что как-то он "знает", что переменная определена, но думает, что она имеет нулевую длину. Или переменная "null" имеет длину нуля автоматически?

Как мне определить эту переменную - или это невозможно?

То, что я хочу сделать, - это сделать что-то для каждого языка в списке (в частности, сделать внешнюю ссылку), но я считаю, что нет смысла пытаться {% for %}/{% endfor %} или что-то еще, если я не могу получить эту работу, Может быть, Sphinx реализует только подмножество Jinja?

В любом случае, пожалуйста, помогите!

Ответы

Ответ 1

Есть как минимум два способа передачи переменных в шаблон:

  • Через html_context:

    Словарь значений для перехода в контекст шаблонов шаблонов для всех страниц. Отдельные значения можно также поместить в этот словарь, используя опцию -A командной строки sphinx-build.

    Пример:

    # conf.py:
html_context = {'num_langs': len(LANGS)}

<!-- template: -->
<p>We have {{ num_langs }} languages</p>

  • Через html_theme_options. Для этого нужно добавить опцию theme.conf (вы можете создать тему, наследуя ее от стандартной):

    [options]
num_langs = 1

    Затем вы можете установить num_langs в conf.py через html_theme_options:

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

    и использовать его в шаблоне:

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