SIOS Coati開発チームの清水です。

今回はSphinxについてです。

Sphinxとは「Pythonでかかれたドキュメント作成ツール」で、PythonやAWS CLIのリファレンスもこのSphinxで作成されているので、みたことがある方は多いかもしれません。

ちなみにSIOS CoatiのマニュアルもSphinxで作成されており、過去にブログでも紹介しました。

SIOS Coatiのオンラインマニュアルの作成方法(前編)


Sphinxでアプリケーションのマニュアルを作成したとき、多くの場合はブラウザ上でも見れるようにオンラインマニュアルの形式で公開すると思います。

そのとき、過去のバージョンのマニュアルをどのように公開するかは、結構悩むポイントだと思います。よくあるパターンとしては、ユーザーがいくつかのバージョンの中から選べるようにすることです。

この機能を用意するには、URLを分割したり、ヘッダー/フッターにスイッチを用意したり、バージョンを自動で追跡させたりと、独自で実装するのは割と大変です。Sphinxを利用しているのであれば、Sphinxの機能を活用していきたいところです。

バージョンを選択できるようにするには、readthedocs のようなホスティングサービスを使うのもひとつの手ですが、今回はホスティングサービスなしでもビルドできる SCVersioning を紹介します。

SCVersioning

https://robpol86.github.io/sphinxcontrib-versioning/index.html

SCVersioningは、複数のバージョンを同時にビルドしてくれて、ページ内にしっかりバージョンを切り替えるためのリンクも用意してくれます。
なお注意点として、マニュアルがgitでバージョン管理されている必要があります。その点だけ、ご注意ください。

インストール

公式に記載の通り pip install  するだけです。

pip install sphinxcontrib-versioning

ここで注意があります。この記事公開時点で、SCVersioningは最新バージョンのSphinxに追従できていないようです。

https://github.com/Robpol86/sphinxcontrib-versioning/issues/42

そのため、公式のものを利用する場合は、Sphinxのバージョンをさげて使用してください。

pip install sphinx==1.5.6

なお Pull-Request に、最新のSphinxに追従したものがあるみたいなので、それを使うのも良いかと思います。(動作は未確認です)

https://github.com/Robpol86/sphinxcontrib-versioning/pull/46

使い方

まず ビルドしたいプロジェクト の Makefile がある場所に移動して、次のコマンドを入力してください。

sphinx-versioning build . _build/html

このコマンドを入力することで、カレントディレクトリをビルドして、ファイルを _build/htmlディレクトリに出力します。
なお、デフォルトだと「masterブランチ」をメインページとなり、すべてのブランチ・タグが生成の対象となります。

基本的に作業は以上になります。とても簡単です。あとは 生成されたファイル(_build/html )を自由に移動すれば完了となります。

ビルドオプション

ビルドオプションをつけないと、すべてブランチ・タグでページを生成します。

そのときは  -W "作成対象とするタグ(正規表現)"  のように指定して、生成対象を決めることができます。

その他、詳細は以下のページに記載されている通りに指定してあげると OK です。

https://robpol86.github.io/sphinxcontrib-versioning/v2.2.1/settings.html

よく使いそうなものをピックアップすると、

-w : 生成対象とするブランチを正規表現で制御

-W : 生成対象とするタグを正規表現で制御

-r : メインページとなるブランチ(タグ)を変更

あたりでしょうか。

基本的には、生成対象以外はデフォルトでも十分使用できるかと思います。

まとめ

今回は Sphinx で作成したマニュアルを、バージョンごとに選択できるようにする SCVersioning を紹介しました。

個人的に SCVersioning の開発リポジトリが最近更新されていないところが気になりますが、とても便利です。

ちょっとしたマニュアルを作った際は、ぜひ使用してみてください。