Python 製ドキュメント作成ツール sphinx に触れてみる

前回の記事で reStructuredText も体験したので今回はいよいよ sphinx を体験してみます。
今回、参考にさせていただいたのはこちらです。
sphinx でドキュメント作成からWeb公開までをやってみた - Qiita

何はともあれまずはインストール。
特定の開発環境に依存して使うわけではないので仮想環境ではなく直接インストールします。

py -3 -m pip install sphinx

今回はバージョン 2.0.1 がインストールされました。

sphinx ではドキュメントをプロジェクトという括りで管理していく。
プロジェクトの作成の前にプロジェクトの ROOT ディレクトリを作成します。
作成した ROOT ディレクトリに移動してプロジェクトの作成コマンドを実行します。

sphinx-quickstart

諸々の質問には基本的にデフォルトのままで以下だけ設定。

> Separate source and build directories (y/n) [n]: y
> Project name: sphinx test
> Author name(s): tachitomonn
> Project release []:
> Project language [en]: ja

これでプロジェクトは作成されたけど HTML などの実際のドキュメントはまだ作成されていない。
make html コマンドで HTML を作成することができる。

make html

すると ROOT ディレクトリの build 以下に作成される。
ROOT ディレクトリの source 内の index.rst を元にして HTML が作成されるので、 source 以下に reST ファイルを作成し、 make html コマンドで HTML を作成していくとのこと。

デザインテーマの変更は conf.py の html_theme の値を変更すればよいとのこと。
変更後、 make html コマンドを実行することでデザインが変更される。

ページを追加してみる。
例えば本のレビューを各本ごとにページとして追加していくなら、 source 下に review ディレクトリを作成。
review ディレクトリ下に各本の rst を作成（明示的に utf-8 でファイルエンコーディング）していく。
続いて index.rst を編集（明示的に utf-8 でファイルエンコーディング）して目次を作成する。
make html コマンドでビルドという流れになる。