Sphinxの魔法にかかってみた

はじめに

最近ドキュメントの整備が最優先重要課題になってきたので、ドキュメントを効率よく書くための方法を調査していました。
年初くらいから調査していて、

• 「ドキュメントを作りたくなってしまう魔法のツール Sphinx」 とか
• 「遷移図生成ツール blockdiagの紹介]」 とか
• 「本当のドキュメントと向き合えますか」 を見て

ようやく「Sphinxにしよう！」と決心したので、Windows環境にSphinxを導入してみました。

そこで、この記事ではWindows環境にSphinxを導入するための手順を紹介したいと思います。
記事の作成にあたって、次のサイトを参考にさせていただきました。

• 「blockdiag を WindowsXP で動かす」
• 「OmakeでSphinxを自動継続ビルドしてみよう」

目標

この記事では、次のことが実現できる環境を構築します。

• Sphinxを使って、テキストファイル(reStructuredText形式)からHTMLファイルを自動生成できる
• ダイアグシリーズ(blockdiag, seqdiag, actdiag, nwdiag)を使って、テキストファイルから自動生成した遷移図などをHTMLファイルに組み込むことができる
• OMakeを使って、テキストファイルの更新を監視して、HTMLファイルを継続監視ビルドできる
• ２つ以上の別々のドキュメントを少ない負担で管理できる
• ローカルHTMLの更新時に、ブラウザを自動リロードできる(2011/5/3追記)

インストール

インストール物

インストールを始める前に次のファイルを対応するURLから入手しておきます。

ファイル名	URL	概要
python-2.7.1.msi	http://www.python.jp/Zope/download/pythoncore	Python 2.7.1のインストーラ
setuptools-0.6c11.win32-py2.7.exe	http://pypi.python.org/pypi/setuptools	Python 2.7用setuptoolsのインストーラ
VLGothic-20110414.zip	http://vlgothic.dicey.org/	VLゴシックフォントを含むzipファイル
omake-0.9.8.5-2.msi	http://omake.metaprl.org/download.html	Omake 0.9.8.6のインストーラ

インストール後の状態

インストール後の状態が次のとおりになるようにします。

項目	インストール後の状態
Pythonのインストールディレクトリ	C:\Python27
OMakeのインストールディレクトリ	C:\OMake
環境変数PATH	C:\Python27, C:\Python27\Scripts, C:\OMake\bin が追記されていること
ドキュメント作成の作業用ルートディレクトリ	C:\AllDocs
追加フォントのインストールディレクトリ	C:\AllDocs\Fonts

Pythonのインストール

python-2.7.1.msiを実行して、インストーラの手順に従ってインストールして下さい。
インストール後に、環境変数PATHに C:\Python27 と C:\Python27\Scripts を追記して下さい。

Python setuptoolsのインストール

setuptools-0.6c11.win32-py2.7.exeを実行して、インストーラの手順に従ってインストールして下さい。
インストールすると、easy_installが使用できるようになります。

Sphinxと拡張モジュールのインストール

easy_installを使用してSphinxと拡張モジュールをインストールします。
コマンドプロンプトから次のコマンドを実行して下さい。

2011/5/28追記: sphinxcontrib-seqdiag, sphinxcontrib-actdiag, sphinxcontrib-nwdiagのインストールを追記
2011/5/28追記: 以前の記事を参照してダイアグシリーズをインストールした方は、ダイアグシリーズを最新版にアップグレードするために、easy_install --upgrade blockdiagのように、--upgradeオプションを用いて easy_install を実行して下さい。

PILを書き換える

ダイアグシリーズで日本語を使用する場合は、PILを書き換える必要があります。
「blockdiag を WindowsXP で動かす」の「Step.5 -- PILを書き換える」に従って、_imagingft.pydを修正して下さい。

追加フォントのインストール

• VLGothic-20110414.zipを解凍します。
• 解凍先ディレクトリ内の「VL-Gothic-Regular.ttf」と「VL-PGothic-Regular.ttf」を C:\AllDocs\Fonts にコピーします。

※ C:\WINDOWS\Fonts にコピーする方法が一般的だと思いますが、環境への依存度を減らすためにシステムフォルダとは独立したディレクトリにファイルを配置します。

OMakeのインストール

omake-0.9.8.5-2.msiを実行して、インストーラの手順に従ってインストールして下さい。
インストールすると、環境変数PATHに自動的に C:\OMake\bin が追記されます。

インストール状態の確認

コマンドプロンプトを開きなおして、次のとおりにコマンドを実行して下さい。

2011/5/28追記: sphinxcontrib-seqdiag, sphinxcontrib-actdiag, sphinxcontrib-nwdiagのチェックを追記

一部割愛していますが、pythonとomakeはツールのバージョン、easy_installでインストールしたものはモジュールとごに already the active version in easy-install.pth と出力されればＯＫです。

C:\AllDocs>python --version 
Python 2.7.1

C:\AllDocs>omake --version 
OMake 0.9.8.5 (release 2):
	build [Fri Aug 10 16:10:42 2007]
	on jaoquin-nt
(ç•¥)

C:\AllDocs>easy_install sphinx 
Searching for sphinx
Best match: sphinx 1.0.7
Processing sphinx-1.0.7-py2.7.egg
sphinx 1.0.7 is already the active version in easy-install.pth
(ç•¥)

C:\AllDocs>easy_install blockdiag 
Searching for blockdiag
Best match: blockdiag 0.8.1
Processing blockdiag-0.8.1-py2.7.egg
blockdiag 0.8.1 is already the active version in easy-install.pth
(ç•¥)

C:\AllDocs>easy_install sphinxcontrib-blockdiag 
Searching for sphinxcontrib-blockdiag
Best match: sphinxcontrib-blockdiag 0.8.3
Processing sphinxcontrib_blockdiag-0.8.3-py2.7.egg
sphinxcontrib-blockdiag 0.8.3 is already the active version in easy-install.pth
(ç•¥)

C:\AllDocs>easy_install seqdiag  
Searching for seqdiag
Best match: seqdiag 0.3.4
Processing seqdiag-0.3.4-py2.7.egg
seqdiag 0.3.4 is already the active version in easy-install.pth
(ç•¥)

C:\AllDocs>easy_install sphinxcontrib-seqdiag 
Searching for sphinxcontrib-seqdiag
Best match: sphinxcontrib-seqdiag 0.1.1
Processing sphinxcontrib_seqdiag-0.1.1-py2.7.egg
sphinxcontrib-seqdiag 0.1.1 is already the active version in easy-install.pth
(ç•¥)

C:\AllDocs>easy_install actdiag  
Searching for actdiag
Best match: actdiag 0.1.5
Processing actdiag-0.1.5-py2.7.egg
actdiag 0.1.5 is already the active version in easy-install.pth
(ç•¥)

C:\AllDocs>easy_install sphinxcontrib-actdiag 
Searching for sphinxcontrib-actdiag
Best match: sphinxcontrib-actdiag 0.1.1
Processing sphinxcontrib_actdiag-0.1.1-py2.7.egg
sphinxcontrib-actdiag 0.1.1 is already the active version in easy-install.pth
(ç•¥)

C:\AllDocs>easy_install nwdiag 
Searching for nwdiag
Best match: nwdiag 0.2.4
Processing nwdiag-0.2.4-py2.7.egg
nwdiag 0.2.4 is already the active version in easy-install.pth
(ç•¥)

C:\AllDocs>easy_install sphinxcontrib-nwdiag 
Searching for sphinxcontrib-nwdiag
Best match: sphinxcontrib-nwdiag 0.1.1
Processing sphinxcontrib_nwdiag-0.1.1-py2.7.egg
sphinxcontrib-nwdiag 0.1.1 is already the active version in easy-install.pth
(ç•¥)

2011/5/28更新: sphinxcontrib-seqdiag, sphinxcontrib-actdiag, sphinxcontrib-nwdiagのチェック結果を含む形で全体を更新

Sphinxドキュメントの作成

作業用ディレクトリの構成

２つ以上の独立したドキュメントを作成していくことを考慮して、次のディレクトリ構成になるようにします。

C:\AllDocs          // 全ドキュメント共通の作業用ルートディレクトリ
  |                 // ディレクトリ名は任意
  |   
  +---Fonts         // 追加フォントのインストールディレクトリ
  |                 // ディレクトリ名は後述の additional_fontpath の設定で変更可能
  |
  +---document01    // ドキュメント固有の作業用ディレクトリ
  |                 // ディレクトリ名は任意
  |
  +---document02    // ドキュメント固有の作業用ディレクトリ
  |                 // ディレクトリ名は任意
  |
  +---...

１つ目のドキュメントの作成

sphinx-quickstartを実行して、Sphinxドキュメントの基本ファイル群を生成します。
コマンドプロンプトから次のコマンドを実行して下さい。

mkdir C:\AllDocs\document01
cd C:\AllDocs\document01
sphinx-quickstart

途中で色々と確認されますがリターンキーを連打すればＯＫです。デフォルト値が適用できる項目の場合は、次の入力項目に進みます。デフォルト値が適用できない３つの項目(「Project name」,「Author name(s)」,「Project version」)の場合は、入力が完了するまで次の入力項目に進みません。
デフォルト値が適用できない３つの項目の入力例は次のとおりです。

The project name will occur in several places in the built documentation.
> Project name: document01
> Author name(s): tyuki39

Sphinx has the notion of a "version" and a "release" for the
software. Each version can have multiple releases. For example, for
Python the version is something like 2.5 or 3.0, while the release is
something like 2.5.1 or 3.0a1.  If you don't need this dual structure,
just set both to the same value.
> Project version: 0.1.2

sphinx-quickstartが完了すると、document01内が次のとおりになります。

C:\AllDocs\document01
  |   conf.py      // Sphinxの設定ファイル
  |   index.rst    // Sphinxで整形する前のテキストファイル(reStructuredText形式)
  |   make.bat     // Sphinxが自動生成するドキュメントのビルド用バッチ
  |   Makefile     // (この記事では不使用)Sphinxが自動生成するドキュメントのビルド用Makefile
  |   
  +---_build       // ビルド結果の格納先
  +---_static      // (この記事では不使用)静的コンテンツの格納先
  \---_templates   // (この記事では不使用)カスタムテンプレートの格納先

補足: Sphinxが整形する前のテキストファイルのデフォルトの拡張子は rst です。

common.pyの作成

Sphinxの設定ファイル(conf.py)は、Pythonコードそのものになっています。
このことを利用して、「document01固有の設定」と「今後作成するドキュメントにも共通する設定」を分離するために、 C:\AllDocs\common.py を作成します。

common.py の内容例は次のとおりです。

2011/5/28更新: actdiag, seqdiag, nwdiagの sphinxcontrib 拡張モジュール名の変更に合わせて、extensionsの内容を更新(例: sphinxcontrib_actdiag -> sphinxcontrib.actdiag)
2011/5/28更新: 誤記 acttdiag_antialias を actdiag_antialias に訂正

各設定の概要は次のとおりです。

設定項目	対象モジュール	概要
additional_fontpath	この記事独自	追加フォントのインストールディレクトリを設定しています。この記事では、common.pyからの相対パス(./Fonts)を設定しています。
extensions	Sphinx	Sphinxの拡張モジュールを追加設定しています。blockdiag, actdiag, seqdiag, nwdiagを有効にしています。
source_encoding	Sphinx	Sphinxに与えるテキストファイル(reStructuredTextファイル)の文字コードを設定しています。Windows環境の場合は、shift_jisを設定した方がよいかもしれません。
language	Sphinx	Sphinxが自動生成するドキュメントの言語を設定しています。
html_theme	Sphinx	Sphinxドキュメントのテーマを設定しています。個人的にはデフォルトのテーマよりも sphinxdoc の方が好きです。
html_last_updated_fmt	Sphinx	HTMLに出力するドキュメント生成日時のフォーマットを設定しています。
blockdiag_fontpath	blockdiag	blockdiagで使用するフォントを設定しています。
actdiag_fontpath	actdiag	actkdiagで使用するフォントを設定しています。
seqdiag_fontpath	seqdiag	seqkdiagで使用するフォントを設定しています。
nwdiag_fontpath	nwdiag	nwdiagで使用するフォントを設定しています。
blockdiag_antialias	blockdiag	blockdiagでアンチエイリアスを有効化しています。
actdiag_antialias	actdiag	actdiagでアンチエイリアスを有効化しています。
seqdiag_antialias	seqdiag	seqdiagでアンチエイリアスを有効化しています。
nwdiag_antialias	nwdiag	nwdiagでアンチエイリアスを有効化しています。

補足: common.pyには、conf.pyの設定に追加するもの、またはconf.pyの設定を上書きするものを列挙します。
補足: 上記はあくまでも設定の一例です。
補足: 設定項目の詳細については、対象モジュールのドキュメントを参照して下さい。

conf.pyの編集

common.pyを読み込むためのPythonコードをconf.pyの末尾に追記します。

HTMLの生成

ここまででSphinxの利用環境が整いました。
コマンドプロンプトから次のコマンドを実行すると、SphinxがHTMLを生成してくれます。

make html

コマンドがエラーなく終了し、_build\htmlにindex.htmlなどが生成されればＯＫです。

ドキュメントの自動継続ビルド

index.rstなどのrstファイルを変更する度に make html と打ってHTMLファイルを作り直すのは大変です。
そこで、OMakeの継続監視ビルド機能を利用して、rstファイルの変更に合わせてHTMLファイルを生成できるようにします。

全ドキュメントの一括ビルド用規則の作成

まず、次のコマンドを実行します。

cd C:\AllDocs
omake --install

これで C:\AllDocs がOMakeビルドツリーの基点になります。

次に、OMakefileの中身をいったん空にして、次の一行だけを含むファイルを作成して下さい。

これで C:\AllDocs\document01 がOMakeビルドツリーに組み込まれます。

ドキュメント固有のビルド規則の作成

最後に、C:\AllDocs\document01内に次の内容のOMakefileを作成します。

補足: Sphinxのビルドコマンドは sphinx-build です。
補足: このビルド規則では HTMLファイルを生成していますが、sphinx-buildは他の形式のファイルを生成するためのオプションも備えています。

OMakeによるビルド

この状態でコマンドプロンプトから次のコマンドを実行すると、document01内のrstファイルに対してビルドが実行されます。

cd C:\AllDocs\document01
omake

また、次のコマンドを実行すると、継続監視ビルドモードになります。

cd C:\AllDocs\document01
omake -P --verbose

document01ディレクトリツリー内のrstファイルを変更して、ビルドが自動実行されることを確認して下さい。

２つ目のドキュメントの作成

「common.pyの作成」と「全ドキュメントの一括ビルド用規則の作成」を除く次の手順をdocument02内で実施して下さい。

• sphinx-quickstartの実行
• conf.pyの編集
• ドキュメント固有のビルド規則の作成(document01で作成したファイルのコピーでＯＫです)

また、C:\AllDocs\document02 をOMakeビルドツリーに組み込むために、C:\AllDocs\OMakefile を次のとおりに変更します(空白を一つあけて document02 と記述します)。

これでdocument02も継続監視ビルドが実施できる状態になります。

また、次のコマンドを実行すると document01 と document02 の両方を一括ビルドすることができます。

cd C:\AllDocs
omake

ブラウザの自動リロード(2011/5/3追記)

ローカルのHTMLファイルが更新される度に、ブラウザをリロードするのも大変です。
「Firefoxでの開発を高速化する自動リロードスクリプト」で公開されている「AutoReload」ブックマークレットを使用すると、この手間を省くことができます。
rstファイルを変更すると、継続監視ビルドがローカルHTMLファイルを更新し、ブラウザがローカルHTMLファイルを自動リロードしてくれるので、さらに効率よくドキュメントを書き進められるようになります。

最終状態

以上で目標にしていた環境が構築できました。ビルドによって生成されるファイルを除くと C:\AllDocs ディレクトリツリーの内容は次のとおりになります。

C:\AllDocs
  |   common.py        // 全ドキュメントの共通設定を定義するためのSphinx用ファイル
  |   OMakefile        // 全ドキュメントのビルド規則を定義するためのOMake用ファイル
  |   OMakeroot        // 全体的なビルド規則を定義するためのOMake用ファイル
  |   
  +---document01
  |   |   conf.py      // document01固有の設定を定義するためのSphinx用ファイル
  |   |   index.rst    // Sphinxで整形する前のテキストファイル(reStructuredText)
  |   |   make.bat     // Sphinxが自動生成するドキュメントのビルド用バッチ
  |   |   Makefile     // (この記事では不使用)Sphinxが自動生成するドキュメントのビルド用Makefile
  |   |   OMakefile    // document01のビルド規則を定義するためのOMake用ファイル
  |   |   
  |   +---_build       // ビルド結果の格納先
  |   +---_static      // (この記事では不使用)静的コンテンツの格納先
  |   \---_templates   // (この記事では不使用)カスタムテンプレートの格納先
  |
  \---document02
  |   |   conf.py      // ファイルの用途はdocument01と同じ
  |   |   index.rst    // ファイルの用途はdocument01と同じ
  |   |   make.bat     // ファイルの用途はdocument01と同じ
  |   |   Makefile     // ファイルの用途はdocument01と同じ
  |   |   OMakefile    // ファイルの用途はdocument01と同じ
  |   |   
  |   +---_build       // ディレクトリの用途はdocument01と同じ
  |   +---_static　　  // ディレクトリの用途はdocument01と同じ
  |   \---_templates   // ディレクトリの用途はdocument01と同じ
  |
  \---Fonts
          VL-Gothic-Regular.ttf   // VLゴシックフォント
          VL-PGothic-Regular.ttf  // VLゴシックフォント

注意点

継続監視ビルド中に作成したrstファイルは、継続監視ビルド対象外になるようです。また、継続監視ビルド中は、ディレクトリツリー内に新しいrstファイルを作成できなくなることがあります。
新しいrstファイルを作成する場合は、継続監視ビルドをいったん中止して下さい。

おわりに

ワードプロセッサやスプレッドシートを使用していて次のような問題で困っていないでしょうか。

• ドキュメントの体裁を気にしすぎて作成作業が進まない。
• オートコレクトや自動インデントの機能が余計に働いて困る。
• ドキュメントが比較しにくい。
• ドキュメントを分割して構造化するのが難しい。
• 同一ファイルを複数人が並行作業しつつ変更するのが難しい。
• ドキュメントの一部を抜き出して新たなドキュメントを作成するのが難しい。

そのような方はSphinxの魔法にかかってみることをお奨めします。

Sphinxドキュメントの構成は、「Sphinxのドキュメントサンプル：業務利用例 — Python製ドキュメンテーションビルダー、Sphinxの日本ユーザ会」を参考にすると良いでしょう。

変更履歴

• 2011/5/3: ブラウザの自動リロードに関する記述を追記しました。
• 2011/5/28: ダイアグシリーズのインストール構成の変更に合わせて、記事を更新しました。
  common.pyの誤記を訂正しました。