6

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

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

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

一般来说，有没有关于如何继续构建文档的指导方针？

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

4

1 回答 1

7

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

在编写 Python 代码文档时，通常会将大量文档放在源文件中，即文档字符串中。Sphinx 支持在您的模块中包含文档字符串，并带有名为“autodoc”的扩展（扩展是为 Sphinx 项目提供附加功能的 Python 模块）。

为了使用 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那么我建议：

  1. 将您的教程作为.rst文件放在单独的目录中，
  2. 从其中引用从 API 文档生成的文档以及
  3. 从您的代码注释中在它们旨在说明的地方引用这些教程。

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

我强烈推荐以下内容：

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