torutkのブログ

ソフトウェア・エンジニアのブログ

Sphinxでドキュメント生成（Windowsでの始め方）

コンピュータ

プログラミング関連でドキュメントを作成する場合、章節構成を持つ文章を書き、随所に箇条書き、図表、ソースコードや画面をちりばめることが多いです。また、文書の書式は、HTMLやPDFなど複数の形式で出せると便利です。

Smartdoc、docbookが候補に挙がりますが、両者ともXML文書形式で記述するので、ソース文書作成が慣れないと手間ですし、慣れてもXMLタグ混じりの文章は見やすいものではありません。

Wikiは、ドキュメントを配布する、というときには不向きですし、文書作成がブラウザ上、というのも苦痛です。また、Wikiのサーバーがないところで原稿作成もできません。

そんなとき、Sphinxと呼ばれるツールの存在を知りました。

ざっと見ると、reStructuredTextと呼ばれるテキスト形式で文書を記述し、コマンドでHTMLを生成するものです。reStructuredTextは、Wiki記法の1つとしても使われる書式で、XMLやHTMLタグ混じりの文書に比べて十分見やすいです。ソースコードを取り込む機能もありました。

WindowsマシンにSphinx環境を整える

Sphinxは、Pythonで書かれたツールなので、Python実行環境が必要となります。Linuxではほぼ標準で入っているのですが、Windowsでは滅多に入ってません。また、Pythonにいくつもモジュールを追加する必要があります。

WindowsでSphinxをまとめてインストールするインストーラの作成も進んでいるようです。

なお、インターネットに接続してないPCにインストールできるように、必要なものをひとつひとつダウンロードしインストールする手順を踏みます。

Python

PythonのWindows版を入手しインストールします。Sphinxは、Python 2.x（2.4-2.7）で動くので、ここではPython 2.6を入れることにします。（本日時点での2.x系の最新は2.7.1なので、2.7.1を使う場合、以下の記述で2.6用のところを2.7用に置き換えます）
Python本家サイトより、Windows用インストーラをダウンロードします。

実行すると、インストール場所を聞いてくるので、C:\Python26 などに入れます。インストール後、環境変数PATHに、C:\Pytho26とC:\Python26\Scripts を追加します。

Pythonのeggパッケージを扱うsetuptools

Pythonの追加モジュールでegg形式を扱うツールをインストールします。Pythonのバージョン毎に用意されているので、ここでは2.6用をダウンロードします。

実行するとPythonのディレクトリにツールが追加されます。

Pythonのdocutilsモジュール

Sphinxが依存しているモジュールdocutilsをインストールします。

展開し、ディレクトリ内で　python setup.py install を実行します。

PythonのJinja2モジュール

Sphinxが依存しているモジュールJinja2をインストールします。

展開し、ディレクトリ内で、python setup.py install を実行します。

Pygmentsモジュール

Sphinxが依存しているモジュールPygmentsをインストールします。Pythonのバージョン毎に用意されているので、ここでは2.6用をダウンロードします。

これはeggパッケージになっているので、easy_install Pygments-1.4-py2.6.egg を実行します。

Sphinx

モジュールSphinxをインストールします。Pythonのバージョン毎に用意されているので、ここでは2.6用をダウンロードします。

これはeggパッケージになっているので、easy_install Sphinx-1.0.7-py2.6.egg を実行します。

最初のドキュメント

Sphinxは、最初にドキュメント・プロジェクトを作成し、その中でソースファイル（文書ファイル）を記述し、makeコマンドでHTMLなどの形式のファイルを生成します。
Windowsの場合、makeツールを用意しなくてもmake.batができます。

ドキュメント・プロジェクトの作成

環境変数PATHにPython用設定が追加されており、必要なモジュールがインストールされていれば、コマンドプロンプトで以下を実行します。

C:\Users\torutk\Documents> cd work
C:\Users\torutk\Documents\work> sphinx-quickstart
Welcome to the Sphinx 1.0.7 quickstart utility.

Please enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).

Enter the root path for documentation.
> Root path for the documentation [.]:

行の先頭が>で始まるところは、ユーザーの入力を促しています。とりあえず最低限、以下を入力し、それ以外は Enter のみで進めます。

質問メッセージ 入力内容 意味
Root path for the documentation [.]: hello プロジェクトのトップディレクトリ名
Project Name: Hello 文書の題名
Author name(s): torutk 文書の著者名
Project Version: 0.1 プロジェクトのバージョン番号?

完了すると、Root path... で指定したディレクトリ名の下に初期ファイル・ディレクトリが生成されています。

C:\Users\torutk\Documents\work> dir /B hello
conf.py
index.rst
make.bat
Makefile
_build
_satic
_templates
C:\Users\torutk\Documents\work>

文書を記述する文書ソースファイルは、index.rstです。このファイルおよびここから展開する文書ソースファイルをreStructuredText形式で記述します。記述例はWeb上にいろいろありますので割愛します。

記述後は、makeコマンドで文書生成します。

C:\Users\torutk\Documents\work\hello> make html
   :（略）
C:\Users\torutk\Documents\work\hello>

_buildディレクトリの下にhtmlディレクトリが作られ、その中に一連のHTML用ファイルが生成されます。index.htmlをブラウザで開きます。

なお、文字コードはUTF-8なので、テキスト編集時はUTF-8で作成・保存するようにします。

次回は、PDFへ出力するための追加モジュールのインストールと日本語設定を書く予定です。