使用 Sphinx for Python 项目文档的正确工作流程是什么？ [关闭]答案

【问题标题】：What is the correct workflow in using Sphinx for Python project documentation? [closed]使用 Sphinx for Python 项目文档的正确工作流程是什么？ [关闭]
【发布时间】：2014-02-28 06:29:48
【问题描述】：

我想使用 Sphinx 来记录一个目前没有很好记录的大型项目。特别是我想使用sphinx-apidoc 在我记录它时从代码中生成文档。

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

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

一般而言，对于如何继续构建文档有任何指导方针吗？

注意： 不便之处在于，基本过程假定您已准备好所有代码文档，并且在您继续生成文档时不会进行任何更新。至少这是我需要解决的。

【问题讨论】：

标签： python python-sphinx sphinx-apidoc

【解决方案1】：

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

在编写 Python 代码文档时，通常会放很多源文件中的文档，文档字符串中的文档。狮身人面像支持包含来自模块的文档字符串扩展（扩展是一个 Python 模块，它提供了额外的 Sphinx 项目的功能）称为“autodoc”。

为了使用 autodoc，你需要在 conf.py 中激活它将字符串“sphinx.ext.autodoc”放入分配给扩展配置值。然后，你有一些额外的指令您的处置。

例如，记录函数 io.open()，读取其签名和源文件中的文档字符串，你可以这样写：

.. autofunction:: io.open 你也可以记录整个类，甚至自动模块，使用自动指令的成员选项，喜欢

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

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

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

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

将您的教程作为.rst 文件放在单独的目录中，并
在其中引用从 API 文档生成的文档以及
在您的代码 cmets 中在它们旨在说明的点上引用这些教程。

这应该允许您根据所做更改的位置分别构建教程和 API 文档，并且它们之间仍然存在链接。

我会强烈推荐以下内容：

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

【讨论】：