ドキュメントを部分的に公開/非公開にしてビルドする

日時:2012/11/24
作者:東健太

複数の人/会社が見るドキュメントを書く場合、特定の人には見せてはいけない情報や、逆に特定の会社にだけ見せたい情報が含まれることがあります。

こんなときは、ドキュメントの各部分について公開/非公開を変えつつビルドすることができると非常に便利です。

ここでは、タグを使ってドキュメントの構成を調整するためのテクニックを紹介します。

テクニック

タグをつけてビルドする

ビルドコマンドにタグを渡すことで、ドキュメント内でタグを参照して処理を切り替えることができます。

$ sphinx-build -b html -t tag1 -t tag2 source_dir dest_dir
もしくは
$ make SPHINXOPTS='-t tag1 -t tag2' html

onlyディレクティブ

onlyディレクティブを使うことで、タグの有無を判別して本文を出し分けることができます。

...ユーザ向け本文...

.. only:: not customer
    開発者専用本文...

onlyの引数はandやorが使えるため、使い方次第で複雑な条件も設定できます。

ドキュメント単位での出し分け

ドキュメント内の1文章だけでなく、ドキュメント自体を消し去りたい場合は、conf.pyのexclude_patternsを設定します。

.. toctree::
    :glob:

    /customer/api/*
    /developer/api/*

conf.py:

exclue_patterns = ['_build']

if 'customer' in tags:
    exclude_patterns.append('developer')

exclude_patternsにマッチしたものはビルド対象から外れるため、上記のtoctreeには/deveroper/api/*にマッチするドキュメントは出力されません。

警告

toctreeを2つに分けて、onlyディレクティブで消し去っても同様の見た目にはできますが、ファイル自体はビルドされてしまうため、ナビゲーションがおかしくなり、不要なファイルも見えるようになってしまいます。

ただし、この方法でファイルを消した場合、ファイルが見つからない旨のwarningが出力されます。

ドキュメントの構造設計

一つのドキュメントに複数の見た目を提供する都合上、ドキュメントの構造設計が重要になります。

以下の項目について事前に十分な検討を行なって下さい。

1. ディレクトリ構造

exclude_patternsを使ってマッチングを行うため、タグ一つに対して表示/非表示したいドキュメントはできるだけ簡単なパターンでマッチングできるように纏めておくとよいでしょう。

上記の例では、開発者向けドキュメントをdeveloperディレクトリにまとめておくことで、一つのパターンでexcludeできるようにしています。

2. セクション

onlyディレクティブではセクション自体を出し分けることができません。

セクションの構造を変えなくても複数の人が見られるような構造にするか、ドキュメント全体を入れ替えて対応する必要があります。

変更履歴

2012/11/24:初版(東)