如何使用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__":警衛。