Posted at

Sphinx でPythonのAPIドキュメントを自動作成

More than 3 years have passed since last update.


Sphinx でPythonのAPIドキュメント作成

プログラムを作りながら、自分が作っているクラスのAPIドキュメントが見られたら便利

ということで、Sphinxを使ってPythonモジュールのAPIドキュメントを自動作成・閲覧する方法をまとめました。


環境

Linux(今回はCentOS 6.6でやりました)

Python 2.7 (pipインストール済み)


Sphinxを入れる

Sphinxとは、ドキュメント作成ツールです。(ちなみに、Pythonで書かれています。)

要するに、「知的で美しいドキュメント」が簡単に作れるようになるツールです。

参考: http://docs.sphinx-users.jp/

pipがあれば、簡単にインストール可能です。

$ pip install sphinx


APIドキュメントを自動生成する準備をする

私は、以下のようなディレクトリ構成でやりました。

- project # Pythonプロジェクト

|
|- src # APIドキュメントを自動生成したいPythonコードのディレクトリ
| |- __init__.pyとか
| |- hoge # サブモジュールとか
|
|- docs # Sphinxプロジェクトのディレクトリ

docsディレクトリにAPIドキュメント用のSphinxプロジェクトを作成します。

これはコマンド一発で作成可能です。

$ cd project

$ sphinx-apidoc -F -o docs/ src/

sphinx-apidocコマンドの「-o」オプションにSphinxプロジェクトを作成するディレクトリを、最後の引数に、APIドキュメントを生成したいPythonソースのディレクトリを指定します。

(「-F」オプションは、フル機能?のSphinxプロジェクトを作成するというオプションみたいです。とりあえず、つけておきます。)

これで、srcディレクトリ配下のPythonソースからAPIドキュメントを生成する準備が整いました。(早


自分が作ったPythonソースからAPIドキュメントを作成する。

docsディレクトリに入って、makeコマンドを実行します。

$ cd docs

$ make html

これで、PythonソースからAPIドキュメントが作成されます。

※dotstiringでコメントを書いておけば、それも反映されます。

ちなみに、ソースコードを更新したら

再度、「make html」をすれば、最新のAPIドキュメントになります。


APIドキュメントを見る

docs/_build/html

配下に、HTMLファイルができています。

「index.html」がホームとなるページです。

ローカルで見れるなら、これをブラウザで開きましょう。

リモートのVMでGUIなんてないんじゃい!という人は

$ cd _build/html

$ python -m SimpleHTTPServer

で、簡易Webサーバ立てれば、リモートからみられると思います。

簡易だけあってキャッシュとか無いようなので、

HTMLファイル更新(make html)→ブラウザ更新(F5)

で最新の情報が見られました。


参考

書いている途中で見つけてしまった。

http://qiita.com/icoxfog417/items/9e2eb932b61aa9b9e427

より詳細が知りたい方は↑を見てください。