ドキュメントをはじめたい（sphinx-quickstart）

ドキュメント作成をはじめる場合は、Sphinxに付属しているsphinx-quickstartを使います。 既存のプロジェクト内にドキュメント作成用として追加するケースが多いと思いますが、 MyPROJECT/docs/のようにドキュメント用ディレクトリを用意するとよいです。

1$ cd MyPROJECT
2$ sphinx-quickstart docs
3> Separate source and build directories (y/n) [n]:  # n でOK
4> Project name: # プロジェクト名を入力する
5> Author name(s): # 作成者名を入力する
6> Project release []: # リリース番号を入力する（空欄でもOK）
7> Project language [en]: ja # 日本語に設定

sphinx-quickstart docsを実行すると、 ドキュメントの初期化に必要な基本情報を入力するためのプロンプトが表示されます。 プロンプトに応じて必要な情報を入力します。 設定した内容はdocs/conf.pyであとから書き換えればよいので、 適当に入力してしまっても大丈夫です。

すべてのプロンプトを入力し終えるとdocs/ディレクトリが作成されます。 ディレクトリの構造は次のようになっています。

 1$ tree docs/
 2docs/
 3├── Makefile
 4├── _build/
 5├── _static/
 6├── _templates/
 7├── conf.py
 8├── index.rst
 9└── make.bat
10
113 directories, 4 files

このdocs/直下にドキュメント用のファイルを作成します。 ビルドしたファイルは_build/ビルダー名/に作成されるので、 該当ファイルを開いてローカルで直接確認できます。

Tip

sphinx-quickstartで最初に聞かれる「（ドキュメントの）ソース用とビルド用のディレクトリを分割するか？」だけは、あらかじめ検討しておくとよいと思います。 ディレクトリ構成に関することなので、後から変更するのが難しい（＝めんどくさい）です。