PythonプロジェクトのドキュメントをSphinxで作成する

Pythonのプロジェクトでドキュメントを書く、といったら[Sphinx](http://sphinx-doc.org/)、というくらいSphinxはメジャーなツールになっています。そのため、ここではPythonのプロジェクトドキュメントをSphinxで作成する手順について解説します。

## Sphinxのインストール

Sphinxについては、日本ユーザー会のサイトで詳しく解説されています。当然、インストールの手順も記載されています。

[Sphinx-Users.jp](http://sphinx-users.jp/gettingstarted/index.html)

上記の解説では`easy_install`を使用していますが、`pip install Sphinx`や、Anaconda/Minicondaを使っていれば`conda install Sphinx`でも導入可能です。

※2015/8/2現在、Sphinxが依存するBabelの最新版2.0ではPython3環境において[不具合があります](https://github.com/mitsuhiko/babel/issues/174)。これを回避するには、一旦`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`が冗長になります


## ドキュメントの作成

ここから実際にドキュメントを作成していきます。具体例があった方がイメージがつきやすいと思うので、以下にサンプルのリポジトリを用意しました。フォルダ構成やソースの修正箇所などについてはこちらを参照した方がわかり易いと思います。

[icoxfog417/python_doc_sample](https://github.com/icoxfog417/python_doc_sample)

まず、Pythonプロジェクトの直下に`docs`というフォルダを作成し、そこにドキュメントを作成していきます。
作成した`docs`フォルダに移動し、`sphinx-quickstart`を実行し、ひな形を作成します。

`sphinx-quickstart`

このコマンドの詳細については、[こちらのページ](http://sphinx-users.jp/gettingstarted/make_project.html)にある「sphinx-quickstartの詳細説明」を参照してください。


これでドキュメントはの準備は整いました。ただ、APIリファレンスのようなものは当然ソースコードから自動で生成したいものです。Sphinxでは、`sphinx-apidoc`を利用しこのソースコードからのドキュメント生成を行わせることができます。
以下コマンドでは、`docs`フォルダ内の`apis`に、Pythonパッケージである`python_doc_sample`のドキュメントを生成しています(コマンドはプロジェクトのルートから実行)。

`sphinx-apidoc -f -o docs/apis python_doc_sample`

※importの仕方によっては、importしたものの文書まで芋づる式に作成されてしまうので注意([こちら参照](http://shouhei.github.io/blog/2014/12/29/shpinxdeapifalsedokiyumentosheng-cheng-wosurushi-falsezhu-yi-dian/))。

これでプロジェクトに関する文書とAPIリファレンスが整いました。何れも、文書は拡張子が`.rst`である[reStructuredText](http://docs.sphinx-users.jp/rest.html)形式で書かれています。最終的には、これをHTML形式に変換する必要があります。
そのためのコマンドが`sphinx-build`ですが、`make`を使用する方が簡単です(Windowsでも、`sphinx-quickstart`を実行した際`make.bat`が作成されるので利用可能です)。

`make html`

と、コマンドを実行する前に`conf.py`を編集しておきます(`docs`フォルダの直下にあるはずです)。
なぜなら、デフォルトではPythonコードからの自動ドキュメント作成はオンになっていないためです。

```conf.py
...
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ページが参照できると思います。

![image](https://qiita-image-store.s3.amazonaws.com/0/25990/f019a52f-230f-8faa-84dc-86ed5a671c95.png)

そして、Module Indexのリンクからは、プロジェクト内のパッケージから作成されたAPIドキュメントが検索/参照できると思います。

![image](https://qiita-image-store.s3.amazonaws.com/0/25990/9d310e9b-b7b3-1b38-28dc-b98d3fd648e0.png)

コメントを適切に書いておけば、以下のように見えると思います。

![image](https://qiita-image-store.s3.amazonaws.com/0/25990/84be1c18-159a-c8f4-37b6-e968e1e3b5d0.png)

以後は、ドキュメント(`.rst`)の更新をしたら`make html`でHTMLページが更新されていきます。
ただ、ソースコード側の修正の場合は`sphinx-apidoc`の実行が必要で、これが面倒という場合は簡単なバッチかスクリプトを作ってもよいと思います([サンプル](https://github.com/icoxfog417/python_doc_sample/blob/master/make_docs.py))。

上記で紹介したコマンドは以下にリファレンスがまとまっているので、オプションの意味などを確認する際に参考にしてください。

[Sphinx Documentation](http://docs.sphinx-users.jp/invocation.html)

## ドキュメントの公開

作成したドキュメントはHTMLページなので、サーバーにおけば簡単に公開できます。GitHubリポジトリの場合、GitHub pagesが使えます。

[Creating Project Pages manually](https://help.github.com/articles/creating-project-pages-manually/)

HTMLページが作成される`_build`フォルダを`gh-pages`にpushすればそれで公開は完了です。ただ、注意点として静的ファイルへのアクセスのため`.nojekyll`ファイルが必要な点に注意してください。

* [Sphinx でドキュメントを作成して GitHub Pages で公開するまで](http://qiita.com/key-amb/items/4f799fed51734987f3c5)
* [Publishing sphinx-generated docs on github](http://daler.github.io/sphinxdoc-test/includeme.html)

これでPythonプロジェクトのドキュメントをSphinxで作成し、公開できるようになりました！