Hatena::ブログ(Diary)

ふぞろいのGENGOたち RSSフィード Twitter

2011-05-02

Sphinxの魔法にかかってみた

はじめに

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

年初くらいから調査していて、

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

そこで、この記事ではWindows環境にSphinxを導入するための手順を紹介したいと思います。

記事の作成にあたって、次のサイトを参考にさせていただきました。


目標

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


インストール

インストール

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

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

インストール後の状態

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

項目インストール後の状態
PythonインストールディレクトリC:\Python27
OMakeのインストールディレクトリC:\OMake
環境変数PATHC:\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)を設定しています。
extensionsSphinxSphinxの拡張モジュールを追加設定しています。blockdiag, actdiag, seqdiag, nwdiagを有効にしています。
source_encodingSphinxSphinxに与えるテキストファイル(reStructuredTextファイル)の文字コードを設定しています。Windows環境の場合は、shift_jisを設定した方がよいかもしれません。
languageSphinxSphinxが自動生成するドキュメントの言語を設定しています。
html_themeSphinxSphinxドキュメントのテーマを設定しています。個人的にはデフォルトのテーマよりも sphinxdoc の方が好きです。
html_last_updated_fmtSphinxHTMLに出力するドキュメント生成日時のフォーマットを設定しています。
blockdiag_fontpathblockdiagblockdiagで使用するフォントを設定しています。
actdiag_fontpathactdiagactkdiagで使用するフォントを設定しています。
seqdiag_fontpathseqdiagseqkdiagで使用するフォントを設定しています。
nwdiag_fontpathnwdiagnwdiagで使用するフォントを設定しています。
blockdiag_antialiasblockdiagblockdiagでアンチエイリアスを有効化しています。
actdiag_antialiasactdiagactdiagでアンチエイリアスを有効化しています。
seqdiag_antialiasseqdiagseqdiagでアンチエイリアスを有効化しています。
nwdiag_antialiasnwdiagnwdiagでアンチエイリアスを有効化しています。

補足: common.pyには、conf.pyの設定に追加するもの、またはconf.pyの設定を上書きするものを列挙します。

補足: 上記はあくまでも設定の一例です。

補足: 設定項目の詳細については、対象モジュールのドキュメントを参照して下さい。


conf.pyの編集

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


HTMLの生成

ここまででSphinxの利用環境が整いました。

コマンドプロンプトから次のコマンドを実行すると、SphinxHTMLを生成してくれます。

make html

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


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

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の誤記を訂正しました。

名無し名無し 2016/06/30 13:17 現在omakeの旧サイトからwindows用インストーラーがダウンロードできない状態なのですが、それを所有していましたらどこかへアップロードしていただけないでしょうか。よろしくお願いいたします。
一応他のサイトの方にもお願いしています。

名無し名無し 2016/06/30 13:20 現在、omakeの旧サイトからwindowsインストーラーがダウンロードできない状態なのですが、それを所有していましたらどこかへアップロードしていただけないでしょうか。よろしくお願いいたします。
一応他のサイトの方にもお願いしています。

スパム対策のためのダミーです。もし見えても何も入力しないでください
ゲスト


画像認証