[Python] Sphinxでドキュメントを自動生成する
自分でライブラリなどを作っていると、機能追加のたびにドキュメントも書かなくてはなりません。
そんな手間を少しでも省くためにドキュメントを自動生成できる環境を整えます。
環境
- Python3.7.1
Sphinxをインストール
Pythonで書かれたドキュメント作成ツールの「Sphinx」をインストールしたいと思います。
pipを利用すれば簡単にインストールできます。
pip install sphinx
ドキュメントを自動生成する
今回は、筆者が作ったライブラリ「Django-Boost」を例に進めていきます。
ディレクトリ構成
こんな感じのディレクトリ構成になっています。
├── config
│ └── # サンプルプロジェクトの設定ファイル群
├── django_boost
│ └── # プロジェクト本体 <-- ドキュメント自動生成の対象
└── example
└── # サンプルプロジェクト <-- ドキュメント生成の対象外
ここにドキュメント用のディレクトリdocsを追加します。
mkdir docs
├── config
│ └── # サンプルプロジェクトの設定ファイル群
├── django_boost
│ └── # プロジェクト本体 <-- ドキュメント自動生成の対象
├── docs
│ └── # ここに自動生成されたドキュメントファイルが入る予定
└── example
└── # サンプルプロジェクト <-- ドキュメント生成の対象外
自動生成の下準備
docsディレクトリにドキュメント用のSphinxプロジェクトを作成します。
以下のコマンドを実行するだけで自動生成の下準備は完了です。
sphinx-apidoc -F -o docs/ django_boost/
-Fオプションを有効にするとフル機能のSphinxプロジェクトを作成出来るらしいです。(とりあえずつけておいて損はないはず)-oオプションでプロジェクトの作成先のディレクトリを指定します。- 最後にドキュメントの生成対象のディレクトリを指定します。今回は
django_boost/、ここは各環境に合わせて変更してください。
コマンドを実行すると、docs以下にいくつかファイルが作成されると思います。
これで自動生成の下準備は完了です。
自動生成する
いよいよ自動生成します。
と言っても今までインストールを含め2,3コマンドを実行しただけですのでいよいよってほどでもありませんが…
docsディレクトリ下に移動してmakeコマンドを実行するだけです。
cd docs
make html
作成されたドキュメントを確認する
作成されたドキュメントはdocs/_build/html配下にあります。
index.htmlがホームとなるページです。
ブラウザ等で開けば確認できるはずです。
まとめ
- Sphinxを使えば超お手軽にドキュメントの作成ができる。