如何使用 Sphinx 记录 Python 包

Question

我正在尝试用 Python 记录一个包。目前我有以下目录结构：

.
└── project
    ├── _build
    │   ├── doctrees
    │   └── html
    │       ├── _sources
    │       └── _static
    ├── conf.py
    ├── index.rst
    ├── __init__.py
    ├── make.bat
    ├── Makefile
    ├── mod1
    │   ├── foo.py
    │   └── __init__.py
    ├── mod2
    │   ├── bar.py
    │   └── __init__.py
    ├── _static
    └── _templates

这棵树是sphinx-quickstart 触发的结果。在conf.py 中，我取消了sys.path.insert(0, os.path.abspath('.')) 的注释，而我有extensions = ['sphinx.ext.autodoc']。

我的index.rst 是：

.. FooBar documentation master file, created by
   sphinx-quickstart on Thu Aug 28 14:22:57 2014.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Welcome to FooBar's documentation!
==================================

Contents:

.. toctree::
   :maxdepth: 2

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

在所有__init__.py 中，我都有一个文档字符串，模块foo.py 和bar.py 也是如此。但是，在项目中运行 make html 时，我看不到任何文档。

Answer 1

这是一个大纲：

1. 使用源中的文档字符串记录您的包。
2. 使用 sphinx-quickstart 创建一个 Sphinx 项目。

3. 运行sphinx-apidoc 以生成设置为与autodoc 一起使用的.rst 源。更多信息here。

   将此命令与-F 标志一起使用还可以创建一个完整的Sphinx 项目。如果您的 API 变化很大，您可能需要多次重新运行此命令。

4. 使用 sphinx-build 构建文档。

注意事项：

• Sphinx 需要带有 automodule 或 autoclass 等指令的 .rst 文件才能生成 API 文档。如果没有这些文件，它不会自动从 Python 源中提取任何内容。这与 Epydoc 或 Doxygen 等工具的工作方式不同。此处对差异进行了详细说明：What is the relationship between docutils and Sphinx?。

• 运行 sphinx-apidoc 后，可能需要调整 conf.py 中的 sys.path 以便 autodoc 找到您的模块。

• 为了避免这些问题中出现类似How should I solve the conflict of OptionParser and sphinx-build in a large project?、Is OptionParser in conflict with sphinx? 的奇怪错误，请确保代码结构正确，并在需要时使用if __name__ == "__main__": 保护。