読者です 読者をやめる 読者になる 読者になる

のんびりしているエンジニアの日記

ソフトウェアなどのエンジニア的な何かを書きます。

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をブラウザから開きましょう。

f:id:tereka:20150926005001p:plain

実際に作ったソースコードは以下の表示となっています。

f:id:tereka:20150926005044p:plain

感想

コメントさえ、きちんとしていれば、ドキュメント化をすることができます。
形式を決めて、定期的に実行することで簡単にスピーディーなドキュメント作成ができる点は
非常に良いと思いました。

広告を非表示にする