Pythonのプロジェクトでドキュメントを書く、といったらSphinx、というくらいSphinxはメジャーなツールになっています。そのため、ここではPythonのプロジェクトドキュメントをSphinxで作成する手順について解説します。
Sphinxのインストール
Sphinxについては、日本ユーザー会のサイトで詳しく解説されています。当然、インストールの手順も記載されています。
上記の解説ではeasy_installを使用していますが、pip install Sphinxや、Anaconda/Minicondaを使っていればconda install Sphinxでも導入可能です。
※2015/8/2現在、Sphinxが依存するBabelの最新版2.0ではPython3環境において不具合があります。これを回避するには、一旦pip uninstall babelを実行したのち、pip install babel==1.3でダウングレードするが、GitHub上のブランチから直接インストールしてください(pip install git+https://github.com/mitsuhiko/babel.git@2.0)。
Sphinxはプロジェクト共通で利用するツールなので、virtualenvなどの仮想環境内でなく、グローバルにインストールしておいた方が良いと思います。
※仮想環境内にインストールしてしまうと、プロジェクト本体の依存ライブラリとドキュメントを作るためだけのSphinxの依存ライブラリが混ざってしまい、requirements.txtが冗長になります
ドキュメントの作成
ここから実際にドキュメントを作成していきます。具体例があった方がイメージがつきやすいと思うので、以下にサンプルのリポジトリを用意しました。フォルダ構成やソースの修正箇所などについてはこちらを参照した方がわかり易いと思います。
まず、Pythonプロジェクトの直下にdocsというフォルダを作成し、そこにドキュメントを作成していきます。
作成したdocsフォルダに移動し、sphinx-quickstartを実行し、ひな形を作成します。
sphinx-quickstart
このコマンドの詳細については、こちらのページにある「sphinx-quickstartの詳細説明」を参照してください。
これでドキュメントはの準備は整いました。ただ、APIリファレンスのようなものは当然ソースコードから自動で生成したいものです。Sphinxでは、sphinx-apidocを利用しこのソースコードからのドキュメント生成を行わせることができます。
以下コマンドでは、docsフォルダ内のapisに、Pythonパッケージであるpython_doc_sampleのドキュメントを生成しています(コマンドはプロジェクトのルートから実行)。
sphinx-apidoc -f -o docs/apis python_doc_sample
※importの仕方によっては、importしたものの文書まで芋づる式に作成されてしまうので注意(こちら参照)。
これでプロジェクトに関する文書とAPIリファレンスが整いました。何れも、文書は拡張子が.rstであるreStructuredText形式で書かれています。最終的には、これをHTML形式に変換する必要があります。
そのためのコマンドがsphinx-buildですが、makeを使用する方が簡単です(Windowsでも、sphinx-quickstartを実行した際make.batが作成されるので利用可能です)。
make html
と、コマンドを実行する前にconf.pyを編集しておきます(docsフォルダの直下にあるはずです)。
なぜなら、デフォルトではPythonコードからの自動ドキュメント作成はオンになっていないためです。
...
sys.path.insert(0, os.path.abspath('../'))
...
extensions = ["sphinx.ext.autodoc"]
- 23行目のあたりにある
sys.path.insertで、作成したPythonパッケージへのパスを通しておきます - 33行目あたりの
extensionsで、APIドキュメント作成を行うための拡張sphinx.ext.autodocを追加しておきます
conf.pyを修正後make htmlを実行すれば_buildフォルダにHTMLファイルが作成され、以下のようなWebページが参照できると思います。
そして、Module Indexのリンクからは、プロジェクト内のパッケージから作成されたAPIドキュメントが検索/参照できると思います。
コメントを適切に書いておけば、以下のように見えると思います。
以後は、ドキュメント(.rst)の更新をしたらmake htmlでHTMLページが更新されていきます。
ただ、ソースコード側の修正の場合はsphinx-apidocの実行が必要で、これが面倒という場合は簡単なバッチかスクリプトを作ってもよいと思います(サンプル)。
上記で紹介したコマンドは以下にリファレンスがまとまっているので、オプションの意味などを確認する際に参考にしてください。
ドキュメントの公開
作成したドキュメントはHTMLページなので、サーバーにおけば簡単に公開できます。GitHubリポジトリの場合、GitHub pagesが使えます。
Creating Project Pages manually
HTMLページが作成される_buildフォルダをgh-pagesにpushすればそれで公開は完了です。ただ、注意点として静的ファイルへのアクセスのため.nojekyllファイルが必要な点に注意してください。
これでPythonプロジェクトのドキュメントをSphinxで作成し、公開できるようになりました！