html - Sphinx - 添加要在 HTML 模板中使用的自定义字段/变量

Question

我正在尝试从 .rst 文件中提取元信息以包含在 HTML 模板中。我假设如果我放一些像

.. :newVariable: My Text

到 .rst 文件中，然后使用我自己的模板构建 HTML，我将能够在 HTML header 中包含 newVariable。但它不起作用。我尝试了几件事但无济于事。

这是否可以在不修改 Sphinx 源代码的情况下解决？

Answer 1

在您的 .rst 文件中，在顶部放置一个字段列表，其中包含您要传递的变量名称和值。meta 信息不是必需的，但显示后您可以看到将代码放在哪里。

.. meta::
   :author: My Company, Inc.
   :description: Introduction to ...
   :copyright: Copyright © 2014 My Company, Inc.

:my-variable: my variable's value

.. _introduction:

==================================================
Introduction to ....
==================================================

在您的模板中，您现在可以使用如下代码访问 my-variable:

{%- set my-variable = '' %}
{%- set my-variable_key = 'my-variable' %}
{%- if meta is defined %}
    {%- if my-variable_key in meta.viewkeys() %}
        {%- set my-variable = meta.get(my-variable_key) %}
    {%- endif %}
{%- endif %}

您现在可以使用 my-variable 及其值。

注意模板中，meta指的是第二个字段列表； metatags 是指由 .. meta:: 构建的用于 header 元标记的 docutils 生成的 HTML。它们是两个不同的对象，具有相同的名称...