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

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

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

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

テクニック ¶

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

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

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

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

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

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

ドキュメント内の１文章だけでなく、ドキュメント自体を消し去りたい場合は、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を２つに分けて、onlyディレクティブで消し去っても同様の見た目にはできますが、ファイル自体はビルドされてしまうため、ナビゲーションがおかしくなり、不要なファイルも見えるようになってしまいます。

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

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

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

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

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

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

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