Sphinx + Jenkins で始めるドキュメントの継続的インテグレーション


はじめに

はじめまして、白川です。

システム開発では、多かれ少なかれドキュメントを作成する必要があると思います。
Word、Excelによって作成することが大体と思いますが、いろいろと問題点があるな、と感じるようになりました。

  • 文書自体の整形(改行や改ページ、インデント、文字サイズ)が大変
  • 仕様書が膨大になってくると、何がどこにあるかわからなくなり、内容のメンテナンス・維持が難しくなる

結果として、内容の陳腐化を招いてしまい、
ドキュメントと現実の仕様に差異が発生して、役に立たないドキュメントとなってしまいます。

そうなると、システムの仕様を把握するために、ソースコードをみないといけなくなりますし、
知見が担当者に依存してしまい、担当者が不在になると分からないことが多くなってしまいます。

それを防ぐために、
Python製のドキュメントビルダーであるSphinxを現在試しています。

Sphinxは、reStructedText(reST)形式で記述したテキストファイルを、HTMLやPDF等に変換します。
以下はreSTのサンプルと、実際に出力したHTMLのサンプルです。

スクリーンショット

Sphinxの特徴としては、以下が挙げられます。

  • テキストを編集してビルドすると、きちんとデザイン整形された形でドキュメントをアウトプットできるので、文書自体の整形作業から解放される
  • Word、Excelと違って、テキストベースで差分を確認可能なので、レビューしやすい
  • toctreeディレクティブによって複数のファイルをツリー構造に出来るので、WikiやMarkdownと比較して全体の概要を把握しやすく、どのドキュメントに何が書いてあるか探しやすい
  • Sphinx拡張により、ブロック図やネットワーク図の挿入や、Cacooで作成した画像の挿入も可能
  • HTML、PDF、ePub、Wordなど出力形式が多岐にわたる

Sphinxを上手に活用することで、WordやExcelでドキュメント作成していたときの問題点を解決できるのではないかと思っています。
今回は、開発時のドキュメントの編集から、Jenkinsで自動ビルドして、最新のドキュメントを公開するまでのフローをご紹介します。

sphinxワークフロー

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をインストールしておいて、下記のコマンドを実行することで、

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 を有効にしておきます。

Gitlab_Webhooks

Jenkinsの設定

新規にジョブを作成し、以下の項目を設定します。

■ ソースコード管理
【Repositories】
GitLabで管理しているリポジトリURLを指定します。
【Branches to build】
*/master と設定します。

jenkins_job_scm_setting

■ SCMをポーリング
GitLabに設定したPushイベントに応じてジョブを実行するために、この設定を有効にしておく必要があります。
ただし、スケジュールを入力する必要はありません。

jenkins_job_build_trigger

■ シェルの実行
以下のシェルスクリプトを設定します。

あとは、ジョブを実行するノードにSphinxをインストールしておけば、ビルドから公開まで自動で行えます。

終わりに

実際にSphinxをプロジェクトで回すためには、
実際のシステム開発プロジェクトに適用することを想定した、各種設計ドキュメントの雛形を提供したり、
reSTを覚えてもらうための最小限のガイドラインや補足文書が必要となると思いますが、
ローカルでの編集の確認が簡単にできたり、ビルドから公開まで自動で簡単にできるので、
そういった面でSphinxは非常に使いやすいと思います。


コメントを残す

メールアドレスが公開されることはありません。 * が付いている欄は必須項目です