使用 Sphinx 按需记录项目和模块 [关闭]

Question

我使用Sphinx 来记录 Python 模块。我有一个主 doc 目录，我将单独的 *.rst 文件（每个模块组件上）包含在 index.rst 主文件中。效果很好（请查看source of the Python Library Reference 以了解我是如何做到的）。

我的问题是当我需要为给定的模块组件（而不是整个模块）创建独立的 PDF 时。

假设您的完整模块（库）的结构与Python Library Reference 中的结构相同，然后您可以为crypto 组件的文档创建一个独立的PDF。你会怎么做？

1. 创建不同的索引 (index_2.rst) 并仅包含该文件 (crypto.rst)
2. 评论原始index.rst中的其他文件
3. 使用独立的 Sphinx 文档在 crypto 内创建一个全新的 doc 目录

这些方法似乎都不简单。

请指教。

Answer 1

首先我会创建一个模板，例如index_template.rst。接下来，我将编写一个带有一个参数的 shell 脚本。此参数将指定您要生成的组件，否则它会为所有组件生成一个 index.rst。

然后自定义您的Makefile to support a component parameter。 Makefile 会将此参数传递给 shell 脚本，该脚本每次都会生成一个新的index.rst。

这将允许您执行以下操作：

$ make html
$ make html component=crypto

第一个命令将为所有内容生成一个文档，第二个命令将仅生成 crypto 组件。