ドキュメント管理のためSphinxを導入してGitで管理

ソフトウェア開発においてはドキュメントの変更は頻繁に起こるものです。といいますか、「起きるようにすべき」ってことなんですがね。

ドキュメントの更新は得てして（非常に高い確率で）放置されがちなタスクです。古くなってカビとキノコが生えたドキュメントは役に立たず、誰からも参照されなくなります。そして、リリース直前になって慌てて開発チームが更新作業に追われるのですね。

昨今ではすっかり市民権を得た（と少なくとも見える）アジャイル開発においても、「ドキュメントよりも動くソフトウェアを重視する」という方針のおかげか、ドキュメントは開発中は手を付けず、最後にまとめて作るやりかたも実際に行われてるという話も聞いたことがあります。

僕自身、アジャイル開発を本格的に行った以前のプロジェクトにおいては、開発中にドキュメントは作りませんでした。しかし考えてみれば、そのプロジェクトはWebサービスの開発であって、誰かに仕様を1つにまとめて伝える必要性がそこまで高くないものだったのです。しかし今取り組んでいるプロジェクトは製品として外部に出荷することを想定しており、その意味では仕様をまとめる必要性があります。

しかし、最後にまとめて変更するやり方ではそもそも大変ですし、ミスも生まれやすくなります。何より、ひたすらドキュメントの更新をするのはあまり楽しい作業ではありません。やはり、ドキュメントを開発にともなって随時変更していきたいところです。しかし、それは放置されがちになることは既に述べました。

プログラムのソースコードがなぜアジャイル開発のような頻繁な変更にも耐えられるのかといえば、SubversionやGitのようなバージョン管理システムの貢献が大きいです。コードのどの部分がいつ誰によってどう変更されたのか明確に把握できてこそ、一度書き上げたコードの一部をかいつまんで変更し続けることが容易になるのですね。そうでなければチームは大混乱に陥ります。その意味で、バージョン管理システムが発達していなかった時代、ウォーターフォールしか選択肢がなかったのも頷ける話です。

つまり、ドキュメントの変更を開発に伴って頻繁に行うには、どの部分がいつ誰によってどう変更されたのか把握できるようにしなければなりません。残念ながらExcelやPowerPointではこのことは実現が非常に困難です。

だったら、もしバージョン管理システムによってドキュメントを管理できれば、開発しながらドキュメントも書くということが実現できそうです。そのためには、ソースコード管理システムによって変更を把握できる形式、すなわち「プレーンテキスト」である必要があります。

そこでプレーンテキストからドキュメントを生成する仕組みを導入すればいいと気づくわけですね。有名なものに科学論文向けのTeXがありますが、ソフトウェアのドキュメント向けに開発されたツールの1つとしてSphinxがあります。SphinxはPythonの公式ドキュメントに使われている他、多くのマニュアルやサイトに使われています。

なんか前振りだけで長くなりましたが、まあこういったツールの導入には考え方が重要ですからよしとしましょう。手順自体は大したこと無いんで、簡潔にまとめます。環境はDebian Linuxです。

まず、Sphinxをインストールします。Pythonは既にインストールされているものとします。Debianのパッケージは古いので、公式リポジトリからソースをダウンロードして使います。

$ wget https://bitbucket.org/birkenfeld/sphinx/get/1.2.1.tar.bz2
$ tar jxvf 1.2.1.tar.bz2
$ cd birkenfeld-sphinx-3238dc3d4528/
$ python setup.py build
$ su -
# python setup.py install
# exit

これで/usr/local/bin以下に実行ファイルがインストールされます。次に、ドキュメント管理用のGitリポジトリを用意し、その中でsphinxプロジェクトを初期化します。

$ mkdir foo-doc
$ cd foo-doc
$ git init
$ sphinx-quickstart

sphinx-quickstartを実行すると、幾つか質問されます。その際、プロジェクトの名前と著者名（複数可）だけ答えてあとはデフォルトでいいという説明をよく見かけますが、こんかいはGitで管理する都合上、ソースと生成したドキュメントを分離することにします。以下の質問をされた時に y と答えればいいです。

You have two options for placing the build directory for Sphinx output.
Either, you use a directory "_build" within the root path, or you separate
"source" and "build" directories within the root path.
> Separate source and build directories (y/n) [n]: y

これでSphinxでドキュメントを作成するための基本のファイルが生成されます。 .gitignoreでbuildディレクトリを除外しておきましょう。ドキュメントのソースコードはsource ディレクトリ内にあります。ドキュメントを生成するには、Makefileのあるディレクトリで

make html

などと打てば生成されます。html以外にもpdfなど様々な形式を指定できます。具体的なドキュメントの書き方の詳細については日本ユーザ会のマニュアルなどを参照ください。

※この記事について指摘・意見・提案・感想などありましたら下のコメント欄にどうそ。