Djangoの開発でドキュメントをコードのコメントから自動生成するプロジェクトを担当してた時のDjangoでSphinxを使ってドキュメントを生成する手順を説明していきたいと思います。
その前に、DjangoとSphinxの説明を・・・
Django
Django（ジャンゴ）は、Pythonで実装されたWebアプリケーションフレームワーク。
詳しくはこちら↓↓↓
Sphinx
Sphinxは知的で美しいドキュメントを簡単に作れるようにするツールです。
Pythonのコードからドキュメントを生成するツールです。
HTMLとしてドキュメント生成することもできます。
詳しくはこちら↓↓↓
では、ドキュメント生成の手順を説明していきます。
前提条件
- 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の設定を編集していきます。
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になると思います。それに、自動生成するためにはそれぞれのプログラムのクラスや関数にきちんとコメントを書かないといけなくなるので、そのおかげでコードの可読性も向上するかもです。
ドキュメントとコードという形での仕様書の分断がないので、仕様変更時の修正もかなり楽になると思います。
無駄を省いて、よりプロダクトに価値を付加できるようになればと思います。
コメント