Sphinx入門。Sphinxでdocstringの生成

Sphinx-apidocでpythonのdocstringを自動生成させる
OSX 10.9.4使用。Sphinx v1.1.3使用。
sphinxをインストールした後。さあどうするか。

ディレクトリ構成

├── documents_source/
├── publish/
└── src/
    └── main.py

main.py

# -*- coding: UTF-8 -*-
import sys

def main(name, age=None):
    """Greeting function.

    :param name: Your name.
    :param age: Youre age. (option)
    """
    print "hello, " + name

    if age is not None:
        print "You are " + age

ドキュメントひな形の生成

sphinx-apidocコマンドを実行する。
$ sphinx-apidoc -F -o ./documents_source ./src

上記は初回時のみ。-Fオプションによって構成一式を生成させる。二回目以降はこう実行する。
$ sphinx-apidoc -f -o ./documents_source ./src

documents_source/以下にファイルがたくさんできる。これが生成するドキュメントの元になる。

対象モジュールをimportできるようにする

documents_source/conf.pyを開いて、コメントアウトされているこの箇所を編集し有効にする。autodocモジュールは対象ファイルをimportして読み取るので場所を教える。

conf.py

#sys.path.insert(0, os.path.abspath('.'))
sys.path.insert(0, os.path.abspath('../src'))

ドキュメント出力

sphinx-buildコマンドを実行する。
$ sphinx-build -a ./documents_source ./publish

publish/ディレクトリ以下に閲覧できるドキュメントとして出力されるので確かめる。

以下のように表示される。

この流れを抑えてから公式ドキュメントを読むと理解しやすい。
http://docs.sphinx-users.jp/index.html