如何将 JSON/XML/YAML 数据读入 Sphinx RST 文件以编程方式生成文档页面？

Question

假设我有一个 JSON/YAML/XML 等动物园动物，我想为动物园中的所有动物制作一些文档。 所以我有一个像这样的 JSON：

{
  "zooName": "C town's Zoo",
  "animals": [
    "tiger": {
      "species":"some_species_name_here",
      "weight": 120
    },
    "bear":{
      "species":"some_other_species_name",
      "weight": 100
    }
  ]
}

在另一个 SSG 中，我可以做类似的事情

 > Bring in a JSON file from /data/myfile.json

 > Access some index of that file like [animals][tiger], etc... 

> Show that data as a part of the HTML template that is made by, say, `tiger.rst`

我将如何在 Sphinx 中实现这一点？ 假设我有一个animals.rst ，里面有我所有动物的目录树，然后每个animals.rst都有一个这样的文件。

Tiger
=======================================

Tiger info here.

Species: 
[[ Access my json here and show content from jsonfile[animals][tiger][species] ]]

Weight: 
[[ Access my json here and show content from jsonfile[animals][tiger][weight] ]]

Answer 1

你可以创建一个Sphinx 扩展......但是一个粗略的update.py预处理脚本可能会做：

#!/usr/bin/env python
"""To launch: ``$ python update.py > animals.rst``  """

import json

def headline(text, adorn='='):
    return text + '\n' + adorn*len(text)

def main():
    header = headline('Animals') + '\n\nAnimal info here.\n'
    footer = '\n.. End of document\n'
    mask = '* {name} -- {species}'

    with open('animals.json', 'r') as infile:
        data = json.load(infile)

    print(header)
    for beast in data['animals']:
        print(mask.format(**beast))
    print(footer)

if __name__ == '__main__':
    main()

对于任何更高级的布局，从 Python 字符串format升级到Jinja2模板。

animals.json与您的示例略有不同：

{
  "zooName": "C town's Zoo",
  "animals": [
    {"name": "tiger", "species": "some_species_name_here",  "weight": 120},
    {"name": "bear",  "species": "some_other_species_name", "weight": 100}
  ]
}

最后，向 Sphinx Makefile添加一条规则，如果 JSON 内容发生更改，则触发脚本。