python - 如何使用 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 变化很大，您可能需要多次重新运行此命令。

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

笔记：

• automoduleSphinx 需要带有类似or指令的 .rst 文件autoclass来生成 API 文档。如果没有这些文件，它不会自动从 Python 源中提取任何内容。这与 Epydoc 或 Doxygen 等工具的工作方式不同。此处对差异进行了详细说明：docutils和Sphinx之间的关系是什么？.

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

• 为了避免这些问题中出现的奇怪错误，我应该如何解决大型项目中 OptionParser 和 sphinx-build 的冲突？, OptionParser 和 sphinx 有冲突吗？，确保代码结构正确，if __name__ == "__main__":在需要时使用警卫。