はじめに
はじめまして、白川です。
システム開発では、多かれ少なかれドキュメントを作成する必要があると思います。
Word、Excelによって作成することが大体と思いますが、いろいろと問題点があるな、と感じるようになりました。
- 文書自体の整形（改行や改ページ、インデント、文字サイズ）が大変
- 仕様書が膨大になってくると、何がどこにあるかわからなくなり、内容のメンテナンス・維持が難しくなる
結果として、内容の陳腐化を招いてしまい、
ドキュメントと現実の仕様に差異が発生して、役に立たないドキュメントとなってしまいます。
そうなると、システムの仕様を把握するために、ソースコードをみないといけなくなりますし、
知見が担当者に依存してしまい、担当者が不在になると分からないことが多くなってしまいます。
それを防ぐために、
Python製のドキュメントビルダーであるSphinxを現在試しています。
Sphinxは、reStructedText(reST)形式で記述したテキストファイルを、HTMLやPDF等に変換します。
以下はreSTのサンプルと、実際に出力したHTMLのサンプルです。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 |
================== ユニットテスト方針 ================== 目的 ==== | 堅牢な土台作りの元となるソースコードの信頼性を高めるために、各プログラム部品単位でのテストを実施し、個々のプログラム部品が正しいことを示す。 .. _unit_test_plan: テスト方針 ========== 自動でテストできるように、テストコードを記述することを原則とする。 理由としては、下記の通りである。 - 繰り返し実施でき、回帰テストが容易となる。 - ある箇所のソースコードの変更によって全然別の箇所で影響があって意図しない動作をして不具合になるといった事態を防ぐことが可能となる。 - 分かりやすいユニットテストコードを記述することで、読み手がプログラムの仕様理解をしやすくする。 .. _unit_test_point: テスト記述のポイント ==================== 期待する結果は、明示的に記述すること ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ example の結果がどうなるかを明示的に記述するようにすること。 |
Sphinxの特徴としては、以下が挙げられます。
- テキストを編集してビルドすると、きちんとデザイン整形された形でドキュメントをアウトプットできるので、文書自体の整形作業から解放される
- Word、Excelと違って、テキストベースで差分を確認可能なので、レビューしやすい
- toctreeディレクティブによって複数のファイルをツリー構造に出来るので、WikiやMarkdownと比較して全体の概要を把握しやすく、どのドキュメントに何が書いてあるか探しやすい
- Sphinx拡張により、ブロック図やネットワーク図の挿入や、Cacooで作成した画像の挿入も可能
- HTML、PDF、ePub、Wordなど出力形式が多岐にわたる
Sphinxを上手に活用することで、WordやExcelでドキュメント作成していたときの問題点を解決できるのではないかと思っています。
今回は、開発時のドキュメントの編集から、Jenkinsで自動ビルドして、最新のドキュメントを公開するまでのフローをご紹介します。
1. 開発者は、自身のローカル端末でGitリポジトリから取得したSphinx文書を編集します。
2. 開発者は、編集した内容をGitリポジトリにPushします。
3. masterブランチに変更内容がマージされた段階で、Jenkinsに変更が通知され、Jenkinsはビルドサーバに対してビルドを依頼します。
4. ビルドサーバは、GitリポジトリのmasterブランチからSphinx文書のソースコードを取得し、ビルドを実行し、公開用サーバに転送します。
5. 公開用サーバに配置された最新のHTMLは、ブラウザからアクセスすることで誰でも参照することができます。
ローカル端末でのドキュメントの編集について
ドキュメントの編集はreST形式のテキストを作成・修正する形で行いますが、
ビルドしたときの出力イメージが直観的にどうなるかが分かりにくい面もあります。
確認しようとすると、ビルドコマンドを打って再ビルド、Webブラウザの再リロードが必要となり、面倒くさいです。
MarkdownのようにreSTのWYSIWYGエディタがあればいいのですが、
残念ながら今は無いようです。。
その代わりにですが、
sphinx-autobuildという素敵なツールがあります。
sphinx-autobuildをインストールしておいて、下記のコマンドを実行することで、
|
1 |
sphinx-autobuild [ソースディレクトリ] [ビルド成果物出力ディレクトリ] |
reSTの変更を検知～HTML文書のリビルドを実行し、http://127.0.0.1:8000 から文書を閲覧できます。
さらにHTML文書変更時には、自動的にWebブラウザのリロードが実行されるという優れものです。
GitLabとJenkinsによるドキュメントの自動ビルド
公開用サーバで最新のドキュメントをいつでも見れるようにGitLabとJenkinsそれぞれで設定を行ないます。
GitLabの設定
GitLabのプロジェクトで、
masterにマージされた際にJenkinsに通知するためにWebhookを設定します。
【URL】 http://[JenkinsサーバのURL]/git/notifyCommit?url=[GitリポジトリのURL]
【Trigger】Push events を有効にしておきます。
Jenkinsの設定
新規にジョブを作成し、以下の項目を設定します。
■ ソースコード管理
【Repositories】
GitLabで管理しているリポジトリURLを指定します。
【Branches to build】
*/master と設定します。
■ SCMをポーリング
GitLabに設定したPushイベントに応じてジョブを実行するために、この設定を有効にしておく必要があります。
ただし、スケジュールを入力する必要はありません。
■ シェルの実行
以下のシェルスクリプトを設定します。
|
1 2 |
make clean html rsync -cvl --delete -r [Sphinxのビルドディレクトリ] [公開ディレクトリ] |
あとは、ジョブを実行するノードにSphinxをインストールしておけば、ビルドから公開まで自動で行えます。
終わりに
実際にSphinxをプロジェクトで回すためには、
実際のシステム開発プロジェクトに適用することを想定した、各種設計ドキュメントの雛形を提供したり、
reSTを覚えてもらうための最小限のガイドラインや補足文書が必要となると思いますが、
ローカルでの編集の確認が簡単にできたり、ビルドから公開まで自動で簡単にできるので、
そういった面でSphinxは非常に使いやすいと思います。
