"ドキュメントを部分的に公開/非公開にしてビルドする"の実用例
Sphinx Advent Calendar 2012: 18日目
おひさしぶりのfeizです。久しぶりついでにはてブロに移行してみました。
先日、こんなcookbookを投稿しました。
ドキュメントを部分的に公開/非公開にしてビルドする :: ドキュメンテーションツール スフィンクス Sphinx-users.jp
仕事でお客さん向けのドキュメントを書いてると結構需要のある話なんじゃないかなーと思ってます。
ただ、cookbookには実際の利用例みたいなものをあまり入れられなかったので、この機会に実用例や設計手順をまとめてみようと思います。
前提とするシチュエーション
以下のようなシチュエーションを想定します。
- とあるB2BサービスのAPIサーバーを書いている
- 自社(開発)→サービス元(サービス運用)→エンドユーザー(複数社)
- サービス元とエンドユーザーと自社内の3ロールにそれぞれドキュメントを提供しないといけない
ドキュメント間の関係の設計
内容を考え始める前に、各ドキュメントがどういう関係になるかを設計しておきます。
大抵の場合、自社向けドキュメントには全部載せの内容が出るのが望ましく、自社から離れるに従って内部仕様が削られていくような構造になってほしいはずです。
つまり
自社向けドキュメント⊃サービス元向けドキュメント⊃エンドユーザー向けドキュメント
のような構造です。
これにしたがってビルド時のタグ付けを決めます。
| 自社向け | タグなし |
| サービス元向け | service |
| エンドユーザー向け | user |
更に、エンドユーザーには複数社あるので、"user"に加えて各社それぞれにタグを割り当てておきます。
| A社 | Asha |
| B社 | Bsha |
ドキュメントの構造設計
まずは全部込みの構造を考えてみます。
/spec/ => サービス概要/用語説明など /admin/ => 管理ツールの使い方 /api/ => API毎の詳細仕様 index.rst
こんなかんじにしましょう。
ここから、更に各出力設定によってどういう風に出し/消ししたいかを考えます。
1. /api/
user向けには内部APIは出してはいけないので、userタグがついた場合にはそれらが消えるべきです。
/api/developer/ディレクトリを掘り、内部APIに関するドキュメントは全てそこに纏めることにします。
後は、conf.pyでdeveloperディレクトリのexclude設定を書けばOKです (参照)
if 'user' in tags:
exclude_patterns += ['/api/developer/*']ここで、"/api/developer/*"の代わりに"*/developer/*"という指定にしておくと、どんな場所でもエンドユーザーに見せたくないものは全部developerディレクトリを掘って入れるだけで消し去れます。
以降はこの設定をしたものとして進めます。
2. /service/
サービス概要は、文書丸ごとの出し分けよりはセンテンス単位での出し分けが多そうです。
センテンス毎の出し分けは、onlyディレクティブで実現できます。(参照)
ただし、参照記事にもあるようにセクションの出し分けはできません。
装飾をつけた文字で代用するなどの工夫が必要です。
/service/grossary.rst
:`みんな死ぬしか`: ないじゃない
.. only:: not user
:`ユーザーのみんなには`: ナイショだよ
3. /admin/
serviceとほぼ同じですが、各ユーザー向けの情報（管理画面のログインIDなど）を載せる必要があるかもしれません。
このような場合に各社毎のタグ定義が役に立ちます。
admin.rst
管理画面ログインIDについて
=============================
.. only:: Asha or not user
:ログインID: asha_1234
.. only:: Bsha or not user
:ログインID: bsha_1234このような記述にしておくと、非ユーザー向けドキュメントには全ログインIDが表示され、ユーザー向けドキュメントには対象のユーザー向けのものしか出ないという挙動になります。
書く
出し分けの構造設計までできれば、あとは書くだけです。
ひたすら書いて下さい。
まとめと注意点
- 設計重点
この手法をうまく適用するには、事前の設計がとても重要です。
適当に書いていると、excludeしたドキュメントにリンクが必要になったり、セクションを消す必要が出てきたりしてスムーズに進められません。
- 動作確認する
表示非表示のロジックを仕込み始めると、当然バグを仕込む可能性が出てきます。
adminの項で例に出したログインIDの出し分けなどは、間違って出てしまうとえらいことになります。
動作チェック/出力内容チェックのワークフローは用意しておくべきでしょう。
- 頒布物にソースを含めない
「絶対に見えてはいけない」情報を出し分ける場合には、必ずconf.pyでhtml_copy_sourceをFalseに設定しておくようにしましょう。
ここをTrueにしたままだと、ソースのrstファイルが配布物に含まれてしまうため、onlyで隠しているつもりの情報が見えてしまいます。
