我想使用Sphinx来记录目前没有详细记录的大型项目。特别是我希望使用sphinx-apidoc在我记录代码时从代码中生成文档。
但是我也希望有一些关于如何使用项目等的教程页面，但是当我打电话给sphinx-apidoc时，它会立即生成整个文档。
所以我的问题是：这里正确的工作流程是什么，所以我可以编写手动编写的教程页面，同时更新代码中的文档？请注意，如果我更新手动编写的教程页面（例如，包含在index.txt中）并运行sphinx-apidoc，我将丢失它们，因为整个文档会立即生成。
一般来说，有关如何继续构建文档的指导原则吗？
注意：不便之处在于，基本程序假定您已准备好所有代码文档，并且在您继续生成文档时不会进行任何更新。至少这是我需要解决的问题。
答案 0 :(得分：6)
首先，您运行sphinx-quickstart并接受默认值以设置基本结构仅执行一次并编辑index.rst的目录部分以指向你的教程，介绍等等 - 你至少在单独的.rst文件中概述你的教程。您还可以在网站上修改config.py以添加 autodoc ：
在记录Python代码时，通常需要付出很多代码 源文件中的文档，文档字符串中的文档。狮身人面像 支持从模块中包含文档字符串 扩展（扩展是一个Python模块，提供额外的 Sphinx项目的功能称为“autodoc”。
要使用autodoc，您需要通过put来在conf.py中激活它 字符串'sphinx.ext.autodoc'进入分配给的列表 扩展配置值。然后，你有一些额外的指令 你的处置。
例如，记录函数io.open（），读取其签名 和源文件中的docstring，你写的是：
.. autofunction :: io.open您也可以记录整个类甚至 模块自动，使用auto指令的成员选项， 像
.. automodule :: io：members：autodoc需要导入你的模块 为了提取文档字符串。因此，您必须添加 conf.py中sys.path的适当路径。
将代码模块添加到上面的列表中，然后调用make html来构建您的文档并使用Web浏览器查看它。
进行一些更改，然后再次运行make html。
如果您 使用sphinx-apidoc，那么我建议：
.rst个文件和这应该允许您根据您进行更改的位置单独构建教程和API文档，并且仍然可以在它们之间建立链接。
我强烈推荐以下内容：
sphinx-apidoc调用放入批处理或生成文件中，以便与您使用的设置保持一致。