如何使用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,我有一个docstring,同样适用于模块foo.py和bar.py.但是,make html在项目中运行时,我没有看到任何docstings.

Answer 1

这是一个大纲:

1. 使用源中的docstrings记录您的包.
2. 使用sphinx-quickstart创建一个Sphinx项目.

3. 运行sphinx-apidoc以生成设置用于autodoc的 .rst源.更多信息在这里.

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

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

笔记:

• Sphinx需要带有指令的.rst文件,automodule或者autoclass为了生成API文档.没有这些文件,它不会自动从Python源中提取任何内容.这与Epydoc或Doxygen等工具的工作方式不同.这里的差异更详细一点:docutils和Sphinx之间的关系是什么？.

• 运行sphinx-apidoc之后,可能需要sys.path在conf.py中调整autodoc来查找模块.

• 为了避免像这些问题中的奇怪错误,我应该如何解决大型项目中OptionParser和sphinx-build的冲突？,OptionParser与狮身人面像有冲突吗？,确保代码结构合理,if __name__ == "__main__":在需要时使用防护.