ぼくのかんがえたさいきょうのドキュメントCIかんきょう

1. 前説：こんな書かれ方をするといやなのだ

みなさん、ソフトウェアの設計書ってどうやって書いてます？

....やっぱExcelですよね、この業界。

僕の周囲でもこれはそうなんだけど、個人的には

• 自分一人で設計を書き、
• その設計をもとに自分一人で実装し、
• 実装内容とは無関係な体裁の修正に、十分な時間がかけられ、
• 版の管理は気にしなくてよい

場合になら、たぶんExcelを普通に使うと思う。

ただ、実際の現場だとそんな悠長なことを言っていられるわけでもなく、人が書いた設計書をもとに実装、なんてことは普通で、場合によってはこんな設計書()に出くわすこともありうる。

この場合の正解は、商品情報.商品カテゴリが104のとき、商品情報.個数を加算する。なんだけど、不要な情報が一緒に目に飛び込んでくるのは、正直勘弁してほしいと思う。個人的には。

それに、設計書がMicrosoft Office(xlsだと特に)だとこんなことが起きうる。

1. 共有ディスクに設計書がアップされる
2. 共有ディスクの設計書ファイルをそのまま開くと、反応が悪い上に場合によってはファイルを破壊する可能性もあるので、作業効率を優先してローカルディスクにダウンロード
3. 実装作業中の設計書がいつの間にか更新される（アナウンスはなし）
4. 更新を知らないままローカルファイルで実装を終える
5. 「設計と挙動が違う」とバグ表を切られる

ほかにもいろいろあるが、設計書がMicrosoft Officeだとこんな弊害が起きる、と個人的には考えている。

• 版の管理にはOneDrive for Businessとかが必要で、ふつうのVCSでやるのは悪夢でしかない
• （上に関連するが）リビジョン間で「どこがどう変わったか」を把握するのは、容易なことではないので、一つの最終版ドキュメントにすべての情報を押し込めようとする
• 集中管理されるべき設計書がカジュアルコピーとして拡散するので、どれが本物かわからなくなる
• 設計とは本質的に関係のない「体裁の修正」に、少なくはない労力を割かなければならない

ここまでで終わらせたらただの文句でしかないので、どうすればましになるかを考える。

2. 設計書作成ツールとしてのMicrosoft Office

オフィススイートであるMicrosoft Officeでもっとも設計書作成で使われるのは、表計算ソフトであるExcelじゃないだろうか。

表計算をほとんど必要としない文書なのに、なぜExcelを使うのか、僕なりに考察してみた。

• 日本には昔から「方眼紙文化」があるが、Wordだと方眼紙的なインデントが面倒だが、Excelだとセルを狭めることで方眼紙的なレイアウトを容易に再現できる
• 複数の独立した文書を、「ワークシート」という単位で一つのファイルにまとめることができる
• 日本のオフィスPCには、原則Microsoft Officeが入っているので、環境を選ばない。これは、設計書を「納品」しても、それを相手先でも読むことができることを意味する

Excelを使うときの利点を考えたら、僕ではこれくらいしか思いつかない。読者諸兄で、これ以外の利点がご存知ならご教示いただきたい。

個人的には、これらは何もExcelでなくても達成できるものだと思う。

そう考える理由は以下のとおり。

• 方眼紙的なインデントが必要なのは、「一見して文書の意味付けを把握できるようにしたい」という要求の現れなので、要件に合うような文書構造にすればよい
• 独立した文書を一つのファイルにまとめたいなら、HTMLでもできる
• 環境を選ばないファイル形式には、Adobe PDFというものがある
• 版の管理とリビジョン間の更新差分の管理がMicrosoft Officeだと難しいのは、ファイルフォーマットがバイナリが基本なのが原因なので、原稿をプレーンテキストで記述できれば差分管理はVCSが良しなにしてくれる
• 単一の原稿から複数のフォーマットの成果物を生成できれば、「開発時は開発サーバ上のHTMLを参照」し、「納品にはPDFを使う（必要であれば印刷してもよい）」という方式がとれる
• ドキュメントビルダを経由すれば、規定のマークアップ仕様のもとで、体裁は統一された仕様として構造化された文書に紐づくので、「文書体裁の修正」と「ソフトウェアの設計」を明示的に分離できる

前置きが長くなったが、これらを一度に解決する（と僕が考える）ソフトウェアがある。Sphinxである。

3. 本題：ぼくのかんがえたさいきょうのドキュメントCIかんきょう

まずは目標とすることを挙げてみる。

• 文書の意味付けは標準テンプレートでまかなう
• 版の管理をVCSに分離する
• VCSにコミットされた原稿からのビルドは、人手を介することなく自動的に行われるようにする
• 開発中の設計書が拡散しないよう、Webサーバで参照できるようにする
• 納品用成果物となる設計書は、PDFにして管理する

いろいろ挙げたが、概念的にはこんな図になる。

というわけで、ひとつひとつ書いていく。

3-1. プロジェクトとVCSの設定

プロジェクトについては、プロジェクトを作るの記事に従って sphinx-quickstart を実行して作るだけなので、特に難しいことはないはず。

VCSも、現状Git以上にベターな選択肢はないので、Gitを選択し、外部のホスティングサービスにおいている。ここでは、プライベート／パブリックの切り替えが簡単なAtlassian BitBucketを使っている。

プロジェクトを作ったら、UTF-8を扱えるエディタでreStructuredTextのマークアップ仕様に基づいて設計書を書いていこう。入門記事もある。

3-2. 面倒なことは有能な執事に任せる

「体裁の修正」や「可読性の高い文書ファイルの生成と配置」といった、本質的に設計と関係ないところで労力を割きたくないので、このテの作業はすべてJenkinsに任せる。

BitBucketがプッシュを受け付けたことをトリガーにしてビルドを始めるのが、反映タイミングとしては最速なのだが、これを実現するためにBitBucketにWebHookを設定する。

まず、Jenkins側にBitBucketからのWebHookを受け付けるためのプラグインを導入する。これにはBitBucket pluginを使った。導入自体は、Jenkinsのプラグインマネージャーから行える。

導入したら、ビルドプロジェクトをつくる。

ソースコード管理はGitにする。BitBucketの仕様に従っていれば特に問題はないはず。

次のビルドトリガは Build when a change is pushed to BitBucket を選択する。

最後に実際のジョブだが、 make の成果物をディレクトリにコピーするシェルスクリプトを実行する。

Ubuntu の DocumentRoot である /var/www/html 以下に反映する。

#!/bin/bash
HTML_ROOTDIR=/var/www/html/designdoc
UID_TOMCAT=tomcat
UID_WWW=www-data

LANG_CD=ja

HTML_DIST=$HTML_ROOTDIR/$LANG_CD

EPUB_DIST=$HTML_ROOTDIR/epub/$LANG_CD

PDF_DIST=$HTML_ROOTDIR/pdf/$LANG_CD

make clean html epub latexpdf

PS4='+ [${BASH_SOURCE}:${LINENO}] ${FUNCNAME:+$FUNCNAME(): }'

set -vx

if [ ! -e $HTML_ROOTDIR ]; then

    mkdir $HTML_ROOTDIR

fi

sudo chown -R $UID_TOMCAT:$UID_TOMCAT $HTML_ROOTDIR

if [ ! -e $HTML_DIST ]; then

    mkdir -p $HTML_DIST

fi

rsync -rlDH --delete _build/html $HTML_DIST

if [ ! -e $EPUB_DIST ]; then

    mkdir -p $EPUB_DIST

fi

cp -f _build/epub/MySkill.epub $EPUB_DIST

if [ ! -e $PDF_DIST ]; then

    mkdir -p $PDF_DIST

fi

cp -f _build/latex/MySkill.pdf $PDF_DIST

sudo chown -R $UID_WWW $HTML_ROOTDIR

set +vx

ただ、 Tomcat の実行ユーザーと Apache の実行ユーザーが違うので、 /etc/sudoers をいじって chown を認証なしで実行できるようにしている。

tomcat	ALL=(ALL:ALL)	NOPASSWD:	/bin/chown

このあたり、もっとましなやりようがないものか。我ながらかなりの力技だ（汗）。

Jenkins側の受け入れ態勢ができたところで、BitBucketのプロジェクトにWebHookを送る設定を書く。

[送信先URL]/bitbucket-hook/を宛先にする。

ここまでやれば、手元で原稿を書き、それをBitBucketへプッシュするだけで、実装者にも納品担当者にもうれしい設計文書が作られているはずである。

Sphinxの環境を整える

この記事の目標

• Sphinxの編集環境を作る
• こぎれいなPDFを出力できる環境をWindowsで作る

Sphinx is 何

SphinxはPythonで書かれたドキュメントビルダで、reStructuredTextというマークアップ言語で書かれたソースをこぎれいなHTMLなんかに変換してくれる優れもの。

Sphinxのインストール

詳しくは公式のSphinxのインストール参照。

以下、かいつまんで書く。

1. Pythonをインストール、デフォルトでよいが、公式ではPython 3.xを推奨している模様
2. PIPをインストール
3. pip install -U Sphinxを実行

編集には、Visual Studio CodeとreStructuredText拡張を使っているが、UTF-8が扱えれば使い慣れたエディタで大丈夫。

こぎれいなPDFをWindowsで作る

実はここがこの記事のメイン。

とりあえず、自分で試したWindowsとLinux(Ubuntu)で必要だったパッケージについて、ざっくりまとめた。

ビルダ	html	epub	latex	latexpdf
Windows	〇	〇	△ 要TeX Live	△ 要TeX Live, GNU Make, sh
Linux	〇	〇	△ 要TeX Live	△ 要TeX Live

この表のとおり、SphinxでこぎれいなPDFを作るにはTeXの力を借りる必要があるんだが、これにはTeX Liveというパッケージを使うのが一番簡単だ。

インストーラはInstalling TeX Live over the Internetで取得できる。

Windowsの場合、ネットインストール型のインストーラを使うのがお手軽だが、時間はとてもかかる（2時間くらい？）ことを覚悟したほうがいい。

とはいえ、待っているだけで基本終了するので、特に難しいところはないはず。

また、Sphinxのlatexpdfビルダは、WindowsのDOS窓では処理ができない動きをするので、UNIX由来のツールであるGNU Makeとshを入れておく必要がある。

これにはMSYS2を使うことにした。

QiitaにMSYS2 による gcc 開発環境の構築という記事を投稿している方がいるので、そちらを参考にmakeだけを入れる。

入れたら、C:\msys64\usr\binをパスに追加しておくこと。

ここまでできれば、Sphinxのドキュメントプロジェクトのあるディレクトリでmake.exe latexpdfとやればこぎれいなPDFが出力できていることだろう。

なお、「Sphinxのlatexpdfビルダは、WindowsのDOS窓では処理ができない動きをする」件、一応Issueにも挙がっているようで、日本のメーリングリストでも話題になっているんだけど、なかなかfixしないよなぁ....。