使用Sphinx for Python项目文档的正确工作流是什么？

我想用Sphinx来记录一个大型项目，这个项目目前还没有很好的文档记录。特别是，我想使用

sphinxapidoc

在编写文档时从代码生成文档

然而，我也希望有一些关于如何使用项目等的教程页面，但是当我调用

sphinxapidoc

时，它似乎会立即生成整个文档

所以我的问题是：这里的正确工作流程是什么，这样我就可以编写手动编写的教程页面，同时更新代码中的文档？请注意，如果我更新手动编写的教程页面（例如包含在

index.txt

中）并运行

sphinx apidoc

，我将丢失这些页面，因为整个文档会立即生成

一般来说，是否有关于如何构建文档的指导方针

---

注意：造成不便的原因是，基本过程假设您已经准备好了所有代码文档，并且在生成文档时不会进行任何更新。至少这是我需要解决的问题

首先运行

sphinx quickstart

并接受默认设置以设置基本结构此操作只需执行一次，然后编辑

index.rst

的目录部分以指向教程、介绍等。您至少可以在单独的.rst文件中概述教程。您还可以编辑

config.py

以添加autodoc-从网站：

在编写Python代码文档时，通常会放置大量 源文件中的文档，文档字符串。斯芬克斯 支持使用 扩展（扩展是一个Python模块，提供额外的 Sphinx项目的功能）称为“autodoc”

为了使用autodoc，您需要在conf.py中通过放置 将字符串“sphinx.ext.autodoc”添加到分配给 扩展配置值。然后，您在 你的处置

例如，要记录函数io.open（），请读取其签名 和源文件中的docstring，您可以这样写：

。。autofunction:：io.open您还可以记录整个类，甚至 使用自动指令的成员选项自动创建模块， 像

。。automodule:：io:成员：autodoc需要导入您的模块 以提取文档字符串。因此，您必须添加 conf.py中sys.path的适当路径

如上所述，将代码模块添加到列表中，然后调用

生成html

来构建文档，并使用web浏览器查看文档

进行一些更改，然后再次运行

makehtml

如果您有使用

sphinx apidoc

，我建议：

将教程作为

.rst

文件和

从API文档中引用API文档生成的文档

在代码注释中要说明的地方引用教程 这将允许您分别构建教程和API文档，具体取决于您所做的更改以及它们之间的链接

我强烈建议如下：

• 使用mercurial或git等版本控制系统，以便在运行sphinx之前提交更改
• 将tutorial.rst文件放在项目的VCS下，但不要放在生成的文档文件下
• 将所有教程文件放在一个单独的目录下，并有一个明确的名称，例如教程
• 如果您要交付文档，则为生成的文档使用单独的存储库，用于存储交付
• 始终将文档生成到代码树外部的位置
• 将对sphinx apidoc的调用放入批处理或生成文件中，以便与使用的设置保持一致