ドキュメントを生成したい（sphinx-build）

1$ make help

ドキュメントの生成にはsphinx-buildを使うのですが、その簡易ラッパーとしてMakefileが用意されているのでmakeコマンドを使うことをオススメします。

重要

ゆくゆくはMakefileに依存しないsphinxコマンドを作る予定のようです。 （GitHubのみたので、Issue番号が分かればはる）

make helpコマンドで、利用可能なビルダーを確認できます。 それぞれのビルダーの基本設定はすべてconf.pyにまとめて記述します。

 1# Makefileがあるディレクトリに移動する
 2$ cd $MyPROJECT/docs/
 3
 4# ヘルプを表示する
 5$ make
 6
 7# HTMLを作成する
 8$ make html
 9
10# PDFを作成する
11$ make latexpdf
12
13# リンクを確認する
14$ make linkcheck

例：KumaROOTをビルドする

 1# GitHubにあるリポジトリをクローンする
 2$ git clone https://github.com/shotakaha/kumaroot.git
 3$ cd kumaroot
 4
 5# 仮想環境を立ち上げる
 6$ poetry shell
 7
 8# 必要なパッケージをインストールする
 9(.venv) $ poetry install
10(.venv) $ cd docs/
11
12# HTMLの生成
13(.venv) $ make html
14
15# PDFの生成
16(.venv) $ make latexpdf

例として、このKumaROOTのドキュメントをビルドする方法を書いておきます。

注釈

開発環境を整えるのにpoetryを使っています。 あらかじめインストールが必要です。 詳しくはパッケージ管理したい（poetry）を参照してください。