search
LoginSignup
40

More than 5 years have passed since last update.

posted at

updated at

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/ディレクトリ以下に閲覧できるドキュメントとして出力されるので確かめる。

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

4ebcad1ef56765133d31fcfaa75fe0b0.png

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

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
What you can do with signing up
40