about 4 years ago

最近,開始有做 Document 的需求。在腦海中,用 Python+Document 以 486 的速度搜尋了一下,第一個想到的就是 Sphinx。這是 Pocoo 公司旗下的一個 project 。

Outline

安裝

安裝不外乎就是使用 pip 。

$ pip install sphinx

建立專案

移動到你的 Project Folder,然後執行:

$ sphinx-quickstart

這時會有一連串的問題冒出來,大多是使用預設值即可,少數要修改。以下是一個範例,我留下了我有改動的以及我覺得比較可能會需要調整的選項。我會將文件目錄置於與 source code 平行的 doc 資料夾裡。

> Root path for the documentation [.]: doc
> Separate source and build directories (y/N) [n]:
> Name prefix for templates and static dir [_]:

The project name will occur in several places in the built documentation.
> Project name: SphinxTest
> Author name(s): Jim
> Source file suffix [.rst]:
> Name of your master document (without suffix) [index]:

Please indicate if you want to use one of the following Sphinx extensions:
> autodoc: automatically insert docstrings from modules (y/N) [n]: y
> doctest: automatically test code snippets in doctest blocks (y/N) [n]:
> intersphinx: link between Sphinx documentation of different projects (y/N) [n]:
> todo: write "todo" entries that can be shown or hidden on build (y/N) [n]:
> coverage: checks for documentation coverage (y/N) [n]:

> Create Makefile? (Y/n) [y]:
> Create Windows command file? (Y/n) [y]:

以上這些設定除了跟目錄結構有關的以外,大多數都可以在建立完成後出現的 conf.py 修改。

當你建立完成,你的目錄結構理論上會長這樣:

$ tree SphinxTest
SphinxTest
|-- doc
|   |-- Makefile
|   |-- _build
|   |-- _static
|   |-- _templates
|   |-- conf.py
|   |-- index.rst
|   `-- make.bat
`-- my_mod
    `-- __init__.py

大家會發現,doc 目錄裡面有一個 Makefile 檔,這時候你只需要進到 doc 目錄執行

$ make html

就可以建立你的第一份文件,當然,內容是空白的。Build 好的內容會出現在 _build/html/index.html。到目前為止,你已經幾乎完成官方文件的 First Steps 了。

撰寫

doc 資料夾一開始會有一個 index.rst。這是最頂層的文件。在 index.rsttoctree 區塊,增加一個 tutorial,當我們在編譯的時候,他就會去搜尋 tutorial.rst

doc/index.rst
.. toctree::
  :maxdepth: 5

  tutorial

建立一個簡單的 reStructuredText 文件: tutorial.rst

doc/tutorial.rst
Tutorial for SphinxTest
=======================

This is a test docstring.

重新編譯後打開 _build/html/index.html,就可以看到剛剛編輯的內容。

從 Docstring 自動產生文件

在使用之前,有 2 點需要注意

  1. Path

    Sphinx 檢查 python code 的預設路徑為 sphinx-quickstart 設定的 Root path for the documentation,這裡的例子就是 doc 資料夾。為了要讓 Sphinx 找到我們的 code,我們就必須在 conf.py 額外加上我們的 Project folder。

    doc/conf.py
    sys.path.insert(0, os.path.abspath('..'))
    
  2. 打開 autodoc 的功能

    在 quickstart 建議選項是沒有打開 autodoc 功能的。

    autodoc: automatically insert docstrings from modules (y/N) [n]:
    

    如果你在建立 quickstart 時沒有打開,就需要在 conf.py 把 autodoc 的 extension 加上去。

    doc/conf.py
    extensions = [
    'sphinx.ext.autodoc',
    ]
    

假設我們有一個 module 如下:

my_mod/__init__.py
""" This is a docstring of my module.

This shows how sphinx generate a page from docstring

"""


def hello_world():
    """ Return the string "Hello, world."""
    return "Hello, world."

現在,我們要建立這個 module 的文件,我們到 index.rst 新增一個 Entry: my_mod

doc/index.rst
.. toctree::
  :maxdepth: 5

  tutorial
  my_mod

接著建立 my_mod.rst,利用 automodule 語法,告訴他我們的對象是 my_mod,它會去 parse my_mod.py 的 docstring

doc/my_mod.rst
Document for my module
=======================

.. automodule:: my_mod
    :members:

重新編譯後,文件就依照函數的 docstring 自動產生了。

更新

2014/01/14 - 更新標題 (Sphinx 初體驗 -> Sphinx Documentation 初體驗)

參考資料

  1. Sphinx Tutorial
  2. Using Sphinx to Document Python Code
  3. Documentation of pymongo
← Compile Python Codes Parse decorated function by Sphinx →
 
comments powered by Disqus