PyCharm (IntelliJ) で Sphinx で楽にドキュメントを書く

何故 Sphinx なのか

プロジェクトに参画していると仕様書を書き残したりプロジェクト固有のメモ書きなどを残したりしたい時がよくある。プロジェクトが Redmine などを使用している場合 Wiki に残すなどすれば簡単なのだが、そういった手段が使えないこともある。

そして、日本企業は Excel が大好き である。とかく何の仕様書だろうが Excel を多用する。だが個人的に以下の理由で Excel を使うのは好きではない:

• 閲覧には Microsoft 社が販売する製品が必要である。LibreOffice (OpenOffice) でも良いが再現性が完全ではない
• 構成にもよるがファイルを開くのに時間がかかる
• Git, Subversion などでドキュメントの差分を取るのに向いていない

Sphinx は元々は Python のドキュメントを書くためのツールとして開発された経緯があるようだが、どんなドキュメントにも使用できる。実際に Sphinx を使用しているサイトに関しては http://sphinx-users.jp/example.html が詳しい。

Sphinx は reStructuredText (reST) というフォーマットでドキュメントを書いていく。この reST で書いたドキュメントを HTML や epub, LaTeX や PDF などのフォーマットで出力することができる。reST は Wiki 記法 (例えば Redmine の Textile 記法) より若干複雑なのが残念なのだが、それでも直に HTML などを書くよりは書きやすい。

あと HTML でビルドした場合はテーマを適用することによって簡単に見た目を変えることが可能だし、自動で目次を作成してくれる。また、デフォルトでドキュメント内の検索機能が入っていたりと何かと便利である。

以下 PyCharm (IntelliJ IDEA) の場合を書くが、実際は殆どの部分はコマンドラインで置き換えることができる。

導入

Windows は最初から Python 環境が無いので公式からインストールしておく。OS X や Ubuntu はデフォルトで Python が入っている。

まず以下で Sphinx をインストールする:

$ pip install sphinx  # pip がインストールされている場合
$ easy_install sphinx  # easy_install しかない場合

PyCharm の場合 Settings -> Project Interpreter でインストールやパッケージの確認などできる。ここから右上の緑色の「＋」ボタンで Sphinx をインストールしてもよい。

プロジェクト作成

PyCharm の場合 Sphinx がインストールされていれば Tools -> Sphinx quickstart を選択するとコンソールが起動し設問に答えていくだけで OK である. コマンドラインから行う場合は以下となる:

$ sphinx-quickstart

ソースフォルダとビルドフォルダ (HTML や PDF などを build した時に完成したファイルが格納される) は分けたほうが良い気がする。Separate source and build directories である。

reST で適当に文書を書く

記法はいろいろありすぎるので省略。http://docs.sphinx-users.jp/rest.html あたりを見て書く。

HTML にビルド

コマンドラインから行う場合は Sphinx プロジェクトのルート (make ファイルがある場所) に移動し

$ make html

でよい。reST の構文にエラーがある場合はその旨が表示される。致命的なエラーの場合はビルドされない。

PyCharm の場合はいちいちコマンドラインからビルドしなくても「▶」ボタンでビルド実行することができる。 Run -> Edit Configurations... でスクリーンショットのようにする。

Git 管理する場合

Git や Subversion で管理すると Sphinx プロジェクトは真価を発揮する (Excel なんかと違い差分表示が容易だからだ)。その場合 /build フォルダの下のファイルは生成されるものなので管理対象からは除外する (.gitignore などに追記する)。

ホームページとしてサーバに配備する

/build に生成されたファイルを丸ごと rsync すれば簡単。PyCharm の場合は例によって Settings -> Deployment で配備したいリモートサーバの設定をすれば PyCharm 上で完結する。

デフォルトのテーマの見た目が悪いのをどうにかする

普通にそのまま make html するとあんまり格好良くない HTML ページが出力される。 conf.py の html_theme の値を書き換えると HTML ファイルの見た目を変更することができる。デフォルトの中だと haiku が一番マシだろうか……。

html_theme = 'haiku'

デフォルトで選択できるテーマは http://sphinx-users.jp/cookbook/changetheme/ を見ると確認できる。

筆者は Read the Docs Sphinx Theme (https://github.com/snide/sphinx_rtd_theme) が気に入っている。見た目がかっこいいだけではなくレスポンシブ対応ができるからだ。スマートフォンで見た場合 (若しくは PC でブラウザの幅を狭めていくと) 左メニューが非表示になり三本線のファンクションボタンが表示される。

公式サイトにも書いてあるが導入手順は以下だ:

$ pip install sphinx_rtd_theme

import sphinx_rtd_theme
html_theme = "sphinx_rtd_theme"
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]

あと Twitter Bootstrap のテーマを使用した Sphinx Bootstrap Theme も有力。これも https://pypi.python.org/pypi/sphinx-bootstrap-theme/ に書いてある通り以下で導入できる:

$ pip install sphinx_bootstrap_theme

import sphinx_bootstrap_theme
html_theme = 'bootstrap'
html_theme_path = sphinx_bootstrap_theme.get_html_theme_path()
html_theme_options = {"bootswatch_theme": "united"}  # Bootswatch として united を使用

bootswatch_theme を指定することで Bootswatch 用のテーマをいろいろ適用することができる。指定できるテーマは http://bootswatch.com/ で確認できる。