如何使用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源。更多信息在这里。

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

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

笔记：

• Sphinx需要带有诸如automodule或伪指令的.rst文件，autoclass以便生成API文档。没有这些文件，它不会自动从Python源中提取任何内容。这与Epydoc或Doxygen等工具的工作方式不同。这里将详细说明这些差异：docutils和Sphinx之间是什么关系？

• 运行sphinx-apidoc后，可能需要sys.path在conf.py中进行调整，以使autodoc查找模块。