如何使用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时，我看不到任何docstings。

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__":防护。