我想使用Sphinx来记录一个目前没有充分记录的大型项目。特别是，我想使用sphinx-apidoc在记录代码时从代码中生成文档。
然而，我也想有一些关于如何使用项目等的教程，但当我调用sphinx-apidoc时，它似乎会一次生成整个文档。
所以我的问题是：这里的正确工作流程是什么，这样我就可以编写手动编写的教程页面，同时更新代码中的文档？请注意，如果我更新手动编写的教程页面(例如包含在index.txt中)并运行sphinx-apidoc，我将丢失它们，因为整个文档将同时生成。
一般来说，对于如何构建文档，是否有任何指导方针？
注意：造成不便的原因是，基本过程假设您已经准备好了所有的代码文档，并且在继续生成文档时不会进行任何更新。至少这是我需要解决的问题。
首先运行sphinx-quickstart并接受默认设置来设置基本结构这只需执行一次，然后编辑index.rst的目录部分以指向教程、介绍等-您至少可以在单独的.rst文件中概述教程。您还可以编辑config.py以添加autodoc-来自网站：
在记录Python代码时，通常会放很多源文件中的文档，在文档字符串中。斯芬克斯支持使用扩展(扩展是一个Python模块，它提供Sphinx项目的功能)称为"autodoc"。
为了使用autodoc，您需要在conf.py中通过放置将字符串"sphinx.ext.autodoc"添加到分配给扩展配置值。然后，您可以在您的处置。
例如，要记录函数io.open()，请读取其签名和源文件中的文档字符串，您可以这样写：
autofunction:：io.open您还可以记录整个类，甚至使用自动指令的成员选项，像
autodule:：io:members:autodoc需要导入您的模块以便提取文档字符串。因此，您必须添加conf.py.中sys.path的适当路径
如上所述将您的代码模块添加到列表中，然后调用make html构建文档并使用web浏览器查看。
进行一些更改，然后再次运行make html。
如果您有使用sphinx-apidoc，那么我建议：
- 将教程作为
.rst文件放在一个单独的目录中 - 参考API文档中生成的文档以及
- 在代码注释中，在它们要说明的地方引用教程
这应该允许您单独构建教程和API文档，具体取决于您所做的更改以及它们之间的链接。
我强烈建议如下：
- 使用诸如mercurial或git之类的版本控制系统，以便在运行sphinx之前提交更改
- 将教程.rst文件放在项目的VCS下，但不要放在生成的文档文件下
- 将所有教程文件放在一个有明确名称的单独目录下，例如tutorials
- 如果您正在交付文档，则为您生成的文档使用一个单独的存储库，用于存储交付内容
- 始终将文档生成到代码树外部的位置
- 将您对
sphinx-apidoc的调用放入一个批处理或make文件中，以便与您使用的设置保持一致