2018年以降の記事はGitHub Pagesに移行しました

「Sphinxをはじめよう」を読んで導入したいと思ったので色々考えてみた2

Sphinx

前回のあらすじ

かなり期間があいてしまったが、次に考えるは、実際にどうやって「導入」して「運用」するか。

「納品」するに当たってどんな問題があるか。

このあたり、良い前例があったら知りたいところ。

課題

課題はとりあえず2段階あると思っている。

第1段階: 対開発工程の課題
  • プロジェクトに対しての導入・運用方法

どうやって運用していくか。

ルール決め大事。

第2段階: 対納品工程の課題
  • 納品形式
  • 納品後修正が発生した場合どうするか

顧客(※)に対してどうやって納品するか、またそれをなおすのは誰？

(※) 顧客とは、納品したドキュメントを読む、使う、なおす人。社内の人かもしれないし、社外の人かもしれない。

一つずつ考えていく。

対開発工程

登場人物

以下、架空の登場人物とする。

  • リーダー : Sphinx を導入したい側
    • Sphinx 導入に燃えている人
  • メンバー : 導入した Sphinx を使う側
    • Sphinx および reST は知らない
プロジェクト内での運用方法
  • reST は覚えてもらう
  • とりあえず メンバー にはドキュメント作成に注力してもらい、ファイル生成などは リーダー が整備する
  • 運用はできるだけ git push または svn commit してもらうだけにしたい
    • ただし、いきなりファイルを push してもらうのはちょっと嫌で、 Sintax error くらいは メンバー のローカルでも確認してもらいたいんだけど
      • そうすると Python インストール必須だよなぁ…
      • ローカルで reST プレビューとかできるのかなぁ…
      • GitHub とか使えばプレビューできるんだけど…
    • バージョン管理ツールの使い方は割愛
    • アウトライン(雛形？ / タイトルとか目次とか)はあらかじめ定めておき、空ファイル(ひな形)は リーダー が事前に用意しておく
  • コミット後は、コミットをフックして make (Jenkins などで)して Apache の下とかに展開する

その他にも、そのプロジェクトの風土にあわせたカスタマイズが必要かもしれない。

例えば、「表紙の次のページに変更記録一覧 (Rev.X は誰が何を直して誰が承認したか) みたいな表が必須とか」

対納品工程

登場人物
  • プロジェクト : Sphinx でドキュメントを作成した側
    • 上記開発工程の リーダー と メンバー の集合体
  • 顧客 : Sphinx で作成したドキュメントを納品される側
    • 社内の人かもしれないし、社外の人かもしれない
    • 慣例から、成果物は Office で納品されることが多い
納品形式

なにをどう納品すべきなのか。(開発工程に入る前に、納品形式は両者の間で Fix させておく必要はある)

とりあえず 2 つ考えられる。

  1. reST ファイル、 reST からアウトプットしたファイル、説明書(Sphinx インストール、ビルド手順など)の 3 点セット
    • 対象フォーマットで納品したけど、 reST からどうとでもできるよ形式
  2. reST からアウトプットしたファイルのみ
    • html , pdf などのみ

前者は 顧客 への負担が高すぎ。

かといって後者だと納品後問題が発生した場合どうすればいいのか…。(後述)

裏技として「 Pandoc を使って reST to docx 」という方法も見つけたが、体裁がうまいこと作れなかった…。

納品後修正が発生した場合

誰がどう修正するのか。

これも 2 つ考えられる。

  1. 保守などで プロジェクト が適宜修正する事ができる取り決めの場合
    • この場合は、 Sphinx の環境を使ってなおせばよい
  2. 顧客 が巻き取り、その後ガンガン機能追加・修正していく場合
    • reST を修正してもらう？
    • アウトプットファイル(htmlとか) を直接修正してもらう？

前者は特に問題ない。困るのは後者。

Javadoc とかは、 html ファイルで納品するが、修正するのに直接いじらないよな。やるならソースを直して Javadoc 再生成だろう。

…とすると、 reST も reST を直して再生成するのが一番いいんだけど……それをやってもらう？？

ということで、今考えているのが

  • 開発時は reST で作成、レビューも reST からの OUTPUT で行う
  • 最終納品のときに reST を Office 形式に変換して納品する
    • ただしこの変換、逆はできないのでいったっきり
  • 顧客 には Office でなおしてもらう
  • 改修のお鉢が プロジェクト に回ってきた場合は (-人-)