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

2018年7月30日

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 を設定する。

  1. 「コントロールパネル」→「システムとセキュリティ」→「システム」と進む。
  2. 「システムの詳細設定」をクリックする。
  3. 「詳細設定」のタブをクリックし、「環境変数」をクリックする。
  4. 「システム環境設定」の「新規」をクリックする。
  5. 変数名「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になると思います。それに、自動生成するためにはそれぞれのプログラムのクラスや関数にきちんとコメントを書かないといけなくなるので、そのおかげでコードの可読性も向上するかもです。
ドキュメントとコードという形での仕様書の分断がないので、仕様変更時の修正もかなり楽になると思います。

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

プログラミングDjango, Python, Sphinx

Posted by KoE