Sphinxを使ったAPIドキュメンテーションの作成
Sponsored Links
皆さんこんにちは
お元気ですか。私は元気です。
今日はSphinxを使ったドキュメンテーションを紹介します。
Sphinxを使うとモジュールの表示とコメントを自動的に表示するところを見ていきたいと思います。
Sphinxとは
Sphinxは知的で美しいドキュメントを簡単に作れるようにするツールです。Georg Brandlによって開発され、BSDライセンスのもとで公開されています。
概要 — Sphinx 1.3.2 ドキュメントより
ソースコードAPIについても作れます。後はテキストの編集ももちろん可能です。
Install
インストール自体は簡単に行うことができます。
pip install sphinx
対象プロジェクト
初期プロジェクト構成は以下の内容を想定します。（treeでの出力）
srcの中にソースコードを追加する感覚です。
./
└── src
└── helloworld.py
Sphinxでのコメントの書き方
Sphinxで認識されるように書くコメントは以下のフォーマットです。
def hello_world(name): """ 著者の名前を返す。 :param name: 著者の名前 :return: 文字列 """ return name
この状態でドキュメントを作成してみようと思います。
ドキュメント生成
sphinx-apidoc -F -o docs/ src/
ディレクトリ構成は以下の通りとなります。
./
├── docs
│ ├── Makefile
│ ├── _build
│ ├── _static
│ ├── _templates
│ ├── conf.py
│ ├── helloworld.rst
│ ├── index.rst
│ └── make.bat
└── src
└── helloworld.py
apiドキュメントを構成するためのプロジェクトができました。
これからapiをドキュメント化する為の設定を書き加えていきます。
自動的にビルドするにはconf.pyの以下の行のコメントアウトを外し、
ソースコードディレクトリへのパスを設定する必要があります。
sys.path.insert(0, os.path.abspath('../src'))
設定が終われば、htmlのコードを生成しましょう。生成方法はmakeで可能です。
make html
_build以下に生成されたファイル群ができあがります。htmlディレクトリを開き
index.htmlをブラウザから開きましょう。
実際に作ったソースコードは以下の表示となっています。
感想
コメントさえ、きちんとしていれば、ドキュメント化をすることができます。
形式を決めて、定期的に実行することで簡単にスピーディーなドキュメント作成ができる点は
非常に良いと思いました。
