如何使用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一起使用的第一源。 将此命令与-F标志一起使用也会创建一个完整的Sphinx项目。如果你的API改变很多，你可能需要多次重新运行这个命令。
4. 使用sphinx-build构建文档。

注：

• 狮身人面像，需要.rst与像automodule或autoclass指令文件以生成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__":警卫。