Jinja 模板渲染数据¶

数据写在 Python 里, 文档里只写模板。数据一改, 重新构建, 所有表格自动更新。

数据从哪来¶

conf.py 把 sanhe_me_kb.docs.doc_data 注册成名为 doc_data 的 jinja context:

# ``{jinja} doc_data`` renders its body with these variables, then parses the
# result in the page's own syntax (MyST in .md, reST in .rst).
from sanhe_me_kb.docs import doc_data

jinja_contexts = {
    "doc_data": {
        "doc_data": doc_data,
    },
}

数据本身是一个 list of tuple:

users = [
    (1, "alice"),
    (2, "bob"),
]

{jinja} directive 先用 jinja 渲染它的内容, 再按当前页面的语法解析渲染结果: .md 页面按 MyST 解析, .rst 页面按 reST 解析。

例子 1: Markdown 表格¶

模板:

```{jinja} doc_data
| id | name |
| :--- | :--- |
{% for id, name in doc_data.users -%}
| {{ id }} | {{ name }} |
{% endfor %}
```

结果:

id	name
1	alice
2	bob

例子 2: reST list-table¶

在 .md 页面里要输出 reST, 就把渲染结果包在 {eval-rst} 里。在 .rst 页面里直接写 .. jinja:: doc_data 即可, 不需要 eval-rst。

模板:

````{jinja} doc_data
```{eval-rst}
.. list-table:: Users
    :header-rows: 1
    :widths: 10 90

    * - id
      - name
{% for id, name in doc_data.users %}
    * - {{ id }}
      - {{ name }}
{% endfor %}
```
````

结果:

Users¶
id	name
1	alice
2	bob

例子 3: 不用 reST 的 list-table¶

MyST 自己也有 {list-table} directive, 语法和 reST 一样, 只是外面用 Markdown 的 fence:

Users (MyST list-table)¶
id	name
1	alice
2	bob