我正在编写一个 Django 应用程序来提供一些用 RestructuredText 编写的文档。我有很多用 *.rst 编写的文件，每个文件都很长，有很多节、小节等。
使用 Django 过滤器在单个页面中显示整个文档不是问题，但我宁愿在第一页上只显示主题索引，并链接到我可以显示单个部分/小节的 URL（这将需要一些'previous | up | home | next' 链接我猜...）。以类似于 docbook / XML 到 HTML 转换中的“多 HTML 页面输出”的方式。
谁能指出我构建 *.rst 文档的文档树并解析其中的单个部分的方向，或者提出一种获得类似结果的聪明方法？
选项 1. 包括指向文档其他部分的 URL 链接。
您编写了 index.rst、part1.rst、part2.rst 等。您的 index.rst 具有指向其他部分的链接。这几乎不需要任何工作，除了仔细计划以确保您的 RST HTML 链接是正确的。
没有“解析”。您只需将文档分成几个部分。手动。
[这似乎很明显，我不敢提。]
选择 2. 使用Sphinx。它很好地管理目录和文档间的连接。
但是，对 RST 的 Sphinx 扩展不是由 Django 直接处理的，因此您需要保存 Sphinx 输出，然后在 Django 中显示它。我们使用来自 Sphinx 的 JSON HTML Builder ( http://sphinx.pocoo.org/builders.html?highlight=json#sphinx.builders.html.JSONHTMLBuilder ) 输出。然后我们通过模板渲染这些文档。