Django中.rst文档的多页html输出答案

【问题标题】：Multiple pages html output from a .rst document in DjangoDjango中.rst文档的多页html输出
【发布时间】：2011-04-03 06:30:27
【问题描述】：

我正在编写一个 Django 应用程序来提供一些用 RestructuredText 编写的文档。我有很多用 *.rst 编写的文件，每个文件都很长，有很多节、小节等。

使用 Django 过滤器在单个页面中显示整个文档不是问题，但我宁愿在第一页上只显示主题索引，并链接到我可以显示单个部分/小节的 URL（其中将需要一些“上一个 | 上 | 主页 | 下一个”链接我猜...）。以类似于 docbook / XML 到 HTML 转换中的“多 HTML 页面输出”的方式。

谁能指出我构建 *.rst 文档的文档树并解析其中的单个部分的方向，或者提出一种获得类似结果的聪明方法？

【问题讨论】：

标签： django pagination restructuredtext

【解决方案1】：

选择 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) 输出。然后我们通过模板渲染这些文档。

【讨论】：

谢谢，我一直在考虑选择 1，这似乎是其他文档在其他项目中细分的方式（通常使用我也一直在使用的 Sphinx）。选择 2. 看起来很有趣，但我想（我正在寻找一种方法）： - 将我的文档保存在 *.rst 中，以便我可以使用 Git 管理它们并根据需要生成输出 - 将所有过程保存在 Django无需通过 Sphinx Choice 1. 看起来简单且易于实现：我将查看我的库，看看我的文档如何适应它。谢谢你的建议。