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

Question

我想使用Sphinx来记录一个目前没有详细记录的大型项目.特别是我想用它sphinx-apidoc来记录代码中的文档.

但是我也希望有一些关于如何使用项目等的教程页面,但是当我调用sphinx-apidoc它时,它会立即生成整个文档.

所以我的问题是:这里的工作流程是什么,所以我可以编写手动编写的教程页面,同时更新代码中的文档？请注意,如果我更新手动编写的教程页面(例如包含在内index.txt)并运行,sphinx-apidoc我会丢失它们,因为整个文档会立即生成.

一般来说,有关如何继续构建文档的指导原则吗？

注意:不便之处在于基本过程假定您已经拥有所有代码文档,并且在您继续生成文档时不会进行任何更新.至少这是我需要解决的问题.

Answer 1

首先,你运行sphinx-quickstart并接受默认设置来设置你的基本结构,这只做一次,你编辑目录部分index.rst指向你的教程,给出一个介绍等等 - 你至少在单独的大纲中概述你的教程. rst文件.您还可以编辑config.py以添加autodoc - 来自网站:

在记录Python代码时,通常会在文档字符串中的源文件中放入大量文档.Sphinx支持从模块中包含文档字符串,其扩展名(扩展名是为Sphinx项目提供附加功能的Python模块)称为"autodoc".

为了使用autodoc,你需要在conf.py中通过将字符串'sphinx.ext.autodoc'放入分配给扩展配置值的列表中来激活它.然后,您可以使用其他一些指令.

例如,要记录函数io.open(),从源文件中读取其签名和docstring,您可以这样写:

.. autofunction :: io.open您还可以使用auto指令的成员选项自动记录整个类甚至模块,例如

.. automodule :: io:members:autodoc需要导入你的模块才能解压缩文档字符串.因此,您必须在conf.py中添加sys.path的相应路径.

将代码模块添加到上面的列表中,然后调用make htmlbuildyour文档并使用Web浏览器查看它.

进行一些更改,然后make html再次运行.

如果你必须使用sphinx-apidoc那么我会建议:

1. 将您的教程放在一个单独的目录中作为.rst文件和
2. 从它们内部引用API文档生成的文档
3. 在代码注释中引用教程,以及它们要说明的点.

这应该允许您根据您进行更改的位置单独构建教程和API文档,并且仍然可以在它们之间建立链接.

我强烈推荐以下内容:

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