[ Django ] Sphinx を使ってドキュメントを生成する方法

Django の開発でドキュメントをコードのコメントから自動生成するプロジェクトを担当してた時の Django で Sphinx を使ってドキュメントを生成する手順を説明していきたいと思います。

その前に、 Django と Sphinx の説明を・・・

Django

Django （ジャンゴ）は、 Python で実装されたWebアプリケーションフレームワークです。

詳しくはこちら↓↓↓

ja.wikipedia.org

Django - Wikipedia

https://ja.wikipedia.org/wiki/Django

Sphinx

Sphinx は知的で美しいドキュメントを簡単に作れるようにするツールです。
Python のコードからドキュメントを生成するツールです。
HTML としてドキュメント生成することもできます。

詳しくはこちら↓↓↓

docs.sphinx-users.jp

概要 — Sphinx 1.4.4 ドキュメント

http://docs.sphinx-users.jp

では、ドキュメント生成の手順を説明していきます。

前提条件

Django がすでにインストールされていること

$ pip install Django

上記コマンドで Django をインストールできます。

Sphinx インストール

下記コマンドを実行してインストールします。

$ pip install Sphinx

dot インストール

Mac の人と Windows の人とでインストール方法が異なります。

Mac の人

下記コマンド実行すればインストール完了です。

$ brew install dot

Windows の人

Graphviz の Window版 をダウンロードしてインストールします。

インストールが終了したら Graphviz の実行ファイル dot.exe のインストールパスを確認する。
インストールフォルダを変更していなければ
C:¥Program Files¥Graphviz2.30¥bin¥dot.exe
に実行ファイルがあるはずです。

環境変数 GRAPHVIZ_DOT を設定する。

「コントロールパネル」 → 「システムとセキュリティ」 → 「システム」と進む。
「システムの詳細設定」をクリックする。
「詳細設定」のタブをクリックし、「環境変数」をクリックする。
「システム環境設定」の「新規」をクリックする。
変数名「 GRAPHVIZ_DOT 」、変数値「 C:¥Program Files¥Graphviz2.30¥bin¥dot.exe 」を設定する。

これで、ドキュメントを生成するための準備ができました。
それでは、実際にドキュメントを生成していきたいと思います。

ドキュメントの生成手順

まず、プロジェクトフォルダの直下にドキュメント格納用フォルダを作成します。

$ mkdir /path/to/project/docs

作成した docs フォルダに移動し、 sphinx-quickstart を実行します。

$ cd /path/to/project/docs

$ sphinx-quickstart

sphinx-quickstart を実行すると対話形式で色々聞かれるので、必要な情報を入力していきます。

詳細については下記を確認してみてください。

Sphinx-Users.jp

sphinx-quickstartの詳細説明

http://sphinx-users.jp/gettingstarted/sphinxquickstart.html

Enterで飛ばした質問では主に何を回答しているのかというと、フォルダの配置をどうするか、プラグインを追加するか、などです。ここで入力した内容は、 conf.py というファイルに書き込まれますので、必要に応じていつでも変更がかけられます。少し長いですが、聞かれる内容について軽く紹介します。もちろん、上記3つ以外はデフォルトで問題ありませんので、先が知りたい方は次のセクションに進んでしまって...

次に、 Sphinx の設定を編集していきます。

conf.py の編集

conf.py を編集します。

$ vim /path/to/project/docs/conf.py

sys.path.insert(0, os.path.abspath('..'))
settings.configure()

import 文の下あたりに挿入します。

extensions も変更します。

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.coverage',
    'sphinx.ext.viewcode',
    'sphinx.ext.todo',
    'sphinx.ext.graphviz',
    'sphinx.ext.inheritance_diagram',
    'sphinxcontrib.blockdiag',
]

今回は、「 sphinx.ext.todo 」を利用しているので、「 todo_include_todos 」の値を「 True 」に設定します。

todo_include_todos = True

それ以外にも下記の設定も確認しておきましょう。

project ：プロジェクト名を設定する。
copyright ：コピーライトを設定する。
author ：作成者の情報を設定する。
version ：バージョンを設定する。
language ：言語を設定する。
html_theme ：この Sphinx で利用する HTML のデザインのテーマを設定する。

sphinx-quickstart を実行すれば上記の設定は設定されていると思いますが、もし変更が必要なら、適宜変更していきましょう。

最後に、ドキュメントを生成するコマンドを実行します。

$ cd /path/to/project/docs
$ make html

make html を実行すると _build フォルダに html ファイルが生成されます。

もし、今回自動で生成したドキュメントを、 Django で作った Web アプリケーションと同じURLで確認したい場合は下記の設定を行ってください。

settings.py の編集

settings.py の INSTALLED_APPS に今回作成した docs フォルダを追加します。

INSTALLED_APPS = (
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'django.contrib.admindocs',
    'django.contrib.sites',
    'docs',
)

urls.py の編集

urls.py に Sphinx で生成したドキュメントの URL を設定します。

urlpatterns = [
    ・・・
    url(r'^docs/', include('docs.urls')),
]

これで、「 http://localhost/docs 」にアクセスすると、 Sphinx で生成したドキュメントページを参照することができるようになります。

最後に

Sphinx を利用することで、プログラムの詳細のドキュメントを作成する必要がなくなり、かなりの効率UPになると思います。それに、自動生成するためにはそれぞれのプログラムのクラスや関数にきちんとコメントを書かないといけなくなるので、そのおかげでコードの可読性も向上するかもです。
ドキュメントとコードという形での仕様書の分断がないので、仕様変更時の修正もかなり楽になると思います。

無駄を省いて、よりプロダクトに価値を付加できるようになればと思います。