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

Question

<分区>

Answer 1

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

When documenting Python code, it is common to put a lot of documentation in the source files, in documentation strings. Sphinx supports the inclusion of docstrings from your modules with an extension (an extension is a Python module that provides additional features for Sphinx projects) called “autodoc”.

In order to use autodoc, you need to activate it in conf.py by putting the string 'sphinx.ext.autodoc' into the list assigned to the extensions config value. Then, you have a few additional directives at your disposal.

For example, to document the function io.open(), reading its signature and docstring from the source file, you’d write this:

.. autofunction:: io.open You can also document whole classes or even modules automatically, using member options for the auto directives, like

.. automodule:: io :members: autodoc needs to import your modules in order to extract the docstrings. Therefore, you must add the appropriate path to sys.path in your conf.py.

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

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

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

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

这应该允许您根据更改的位置分别构建教程和 API 文档，并且它们之间仍然有联系。

我会强烈推荐以下内容:

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