如何使用 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構建文檔。

筆記：

• Sphinx 需要帶有automodule或autoclass等指令的 .rst 文件才能生成 API 文檔。 如果沒有這些文件，它不會自動從 Python 源中提取任何內容。 這與 Epydoc 或 Doxygen 等工具的工作方式不同。 這里更詳細地闡述了不同之處： docutils 和 Sphinx 之間的關系是什么？ .

• 運行 sphinx-apidoc 后，可能需要調整 conf.py 中的sys.path以便 autodoc 找到您的模塊。

• 為了避免這些問題中的奇怪錯誤，我應該如何解決大型項目中的 OptionParser 和 sphinx-build 沖突？ , OptionParser 和sphinx 有沖突嗎？ , 確保代碼結構正確，在需要時使用if __name__ == "__main__": guards。