Sphinxの魔法にかかってみた
はじめに
最近ドキュメントの整備が最優先重要課題になってきたので、ドキュメントを効率よく書くための方法を調査していました。
年初くらいから調査していて、
- 「ドキュメントを作りたくなってしまう魔法のツール Sphinx」 とか
- 「遷移図生成ツール blockdiagの紹介]」 とか
- 「本当のドキュメントと向き合えますか」 を見て
ようやく「Sphinxにしよう!」と決心したので、Windows環境にSphinxを導入してみました。
そこで、この記事ではWindows環境にSphinxを導入するための手順を紹介したいと思います。
記事の作成にあたって、次のサイトを参考にさせていただきました。
目標
この記事では、次のことが実現できる環境を構築します。
- Sphinxを使って、テキストファイル(reStructuredText形式)からHTMLファイルを自動生成できる
- ダイアグシリーズ(blockdiag, seqdiag, actdiag, nwdiag)を使って、テキストファイルから自動生成した遷移図などをHTMLファイルに組み込むことができる
- OMakeを使って、テキストファイルの更新を監視して、HTMLファイルを継続監視ビルドできる
- 2つ以上の別々のドキュメントを少ない負担で管理できる
- ローカル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 と出力されればOKです。
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ドキュメントの作成
作業用ディレクトリの構成
2つ以上の独立したドキュメントを作成していくことを考慮して、次のディレクトリ構成になるようにします。
C:\AllDocs // 全ドキュメント共通の作業用ルートディレクトリ | // ディレクトリ名は任意 | +---Fonts // 追加フォントのインストールディレクトリ | // ディレクトリ名は後述の additional_fontpath の設定で変更可能 | +---document01 // ドキュメント固有の作業用ディレクトリ | // ディレクトリ名は任意 | +---document02 // ドキュメント固有の作業用ディレクトリ | // ディレクトリ名は任意 | +---...
1つ目のドキュメントの作成
sphinx-quickstartを実行して、Sphinxドキュメントの基本ファイル群を生成します。
コマンドプロンプトから次のコマンドを実行して下さい。
mkdir C:\AllDocs\document01 cd C:\AllDocs\document01 sphinx-quickstart
途中で色々と確認されますがリターンキーを連打すればOKです。デフォルト値が適用できる項目の場合は、次の入力項目に進みます。デフォルト値が適用できない3つの項目(「Project name」,「Author name(s)」,「Project version」)の場合は、入力が完了するまで次の入力項目に進みません。
デフォルト値が適用できない3つの項目の入力例は次のとおりです。
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の末尾に追記します。
ドキュメントの自動継続ビルド
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ファイルを変更して、ビルドが自動実行されることを確認して下さい。
2つ目のドキュメントの作成
「common.pyの作成」と「全ドキュメントの一括ビルド用規則の作成」を除く次の手順をdocument02内で実施して下さい。
- sphinx-quickstartの実行
- conf.pyの編集
- ドキュメント固有のビルド規則の作成(document01で作成したファイルのコピーでOKです)
また、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の誤記を訂正しました。