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

Question

我想使用狮身人面像记录一个大型项目，目前还没有很好的文档。特别是，我希望在编写文档时使用sphinx-apidoc从代码中生成文档。

不过，我也想要一些关于如何使用项目等的教程，但似乎当我调用sphinx-apidoc时，它会立即生成整个文档。

因此，我的问题是:这里的正确工作流是什么，这样我就可以编写要手动编写的教程页面，同时更新代码中的文档？注意，如果我更新手动编写的教程页面(例如，包含在index.txt中)并运行sphinx-apidoc，我将丢失它们，因为整个文档是一次生成的。

一般来说，是否有任何准则来指导如何进行文档的构建？

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

Answer 1

首先，运行sphinx-quickstart并接受设置基本结构的默认设置--这只需完成一次，并且编辑index.rst的目录部分以指向教程、提供介绍等--您至少可以在单独的.rst文件中概述您的教程。您还可以编辑config.py以添加autodoc -来自网站：

在编写Python代码时，通常会将大量文档放在源文件中、文档字符串中。Sphinx支持从您的模块中包含一个扩展名为“autodoc”的文档字符串(扩展是为Sphinx项目提供附加功能的Python模块)。 为了使用autodoc，您需要在conf.py中激活它，方法是将字符串'sphinx.ext.autodoc‘放入分配给扩展配置值的列表中。然后，您可以使用一些额外的指令。 例如，要记录函数io.open()，从源文件读取其签名和docstring，您可以编写如下代码： 。。自动函数：：io.open您还可以使用自动指令的成员选项自动记录整个类甚至模块，如 。。automodule:：io :members: autodoc需要导入您的模块，以便提取文档字符串。因此，必须将适当的路径添加到sys.path中的conf.py中。

将您的代码模块添加到上面的列表中，然后调用make html构建文档并使用web浏览器查看它。

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

如果让使用sphinx-apidoc，那么我建议：

1. 将教程作为.rst文件和
2. 引用从API文档中生成的文档，再加上
3. 在您的代码注释中引用它们所要演示的部分的教程。

这将允许您分别构建教程和API文档，这取决于您在何处所做的更改，以及它们之间的链接。

我强烈建议如下：

• 使用版本控制系统，如mercurial或git，以便在运行狮身人面像之前提交更改，
• 将教程.rst文件放在项目的VCS下，而不是生成的文档文件下。
• 将所有教程文件放在一个单独的目录下，并有一个清晰的名称，例如教程。
• 如果您正在交付文档，那么为您生成的文档使用一个单独的存储库，用于存储交付。
• 始终将文档生成到代码树的外部的位置()。
• 将对sphinx-apidoc的调用放入批处理或生成文件中，以便与所使用的设置保持一致。