Help us understand the problem. What is going on with this article?

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

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

Why not register and get more from Qiita?
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away