python - 使用 Sphinx 按需记录项目和模块

Question

我使用Sphinx来记录 Python 模块。我有一个主doc目录，我在其中放置*.rst了要包含在index.rst主文件中的各个文件（每个模块组件都在上面）。这很好用（请查看Python 库参考的源代码以了解我是如何做到的）。

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

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

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

这些方法似乎都不是直截了当的。

建议，请。

Answer 1

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

然后自定义您的Makefile 以支持组件参数。index.rstMakefile 会将此参数传递给每次生成一个新的 shell 脚本。

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

$ make html
$ make html component=crypto

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