勘と経験と読経

略すとKKD。ソフトウェア開発やITプロジェクトマネジメントに関するあれこれ。

設計ドキュメント作成ツールとしてSphinxとReVIEWについて調べた

主に作業メモ。ソフトウェア開発プロジェクトでは多かれ少なかれ様々なドキュメントを作成する。一般的にはMicrosoft OfficeなどのOAソフト(つまりWordやExcel)で文書を作成するのだけれども、これが非常に管理し難い。本当はWikiなどで管理するのがいいのだけれども、「納品」とか「持ち出し」を考えたときに、Wikiサーバを立てるのはあまりうまくない。というわけで以前に少しだけチェックしていたドキュメント作成ツールについて改めて調べてみた。

Sphinx

Python製のドキュメント生成ツールである。reStructuredText記法という文法で記述したテキストツールをCUIコンパイルすると、HTMLやPDFなどの各種ドキュメントを生成してくれる。

ReVIEW

結論としてはSphinxでほぼ決まりなのだけれども、どうにもreStructuredText記法には違和感が消えなかったので、Ruby製のドキュメント生成ツールであるReVIEWも調べてみた。

  • インストールはWindowsだとSphinxに比べてハードルは若干高め。CygwinRubyを導入した上でインストールする必要あり。そしてトラップがある(後述)
  • ReVIEW記法は、Wiki記法に近いので非常にしっくりくる。記法としてはベストだと思った。
  • ドキュメントは少ない、というかソフトウェア名称がSEO的に微妙で検索しにくい
  • 基本的にPDFやEPUBを出力するためのソフトウェアであり、現時点ではHTMLの出力は限定的にしかサポートされていない模様。
    • htmlで全体の目次などを出力する機能がうまく動かない。review-indexがうまく動かない(Windows環境の問題かも)。
    • そもそもhtml出力は原稿の事前チェックなどのユースケースだけを想定しているようで、完成品としてhtmlを出力することは考えられていない。review-pdfmakerやreview-epubmakerに相当するhtml出力機能が無い(自分で作ってみることも考えてみたけれども、本筋の「設計書どうにかしたい」欲求から大きく離れてしまうので見送り)

というわけで、使えるか使えないかという視点でみると、残念ながら適用するのは難しそうだった。

Sphinxで設計書を書いてみる

Sphinxで設計ドキュメント類を書くことについては、冒頭でも紹介した以下の情報がある。

ただ、このテンプレートだと何というか「作成のプロセス」がうまくイメージできなかった。というわけで、素直に手元の環境で簡単なサンプルを書いてみることにしてみた。しばらく実験的に更新してみたい。githubで公開しているので興味があれば確認いただきたい

  • 実際に書いてみるとわかることも多い。プロジェクトで実際に運用するまえにいろいろと試行錯誤しておかないとうまく適用できない予感。
  • いろいろと便利な機能(ディレクティブ)があるけれども、これをどのように取捨選択するのかが難しい。
  • 以下、これから試してみたいこと(いつかやる)
    • 構成管理との連携(調べればすぐにでもわかりそう)
    • レビュープロセスの検討と、ドキュメントのレビュー状態の表記方法の整理
    • grossaryディレクティブについて調べ、使い方を考える
    • PDF出力やEPUB出力の方法と使い方の考察
    • Sphinx-Usersのメーリングリストに参加するかどうか検討
    • reStructuredTextを書くためのエディタについての考察

参考

おまけ

上記の検討をしている中で、そういえばWordPressも静的HTMLを吐けるのだから、これで設計書管理するという手もあるなぁと一瞬考えてみたけれども、怖くなったので考えるのはやめた・・・