説明文書を作成する

この節では、 Sphinx を用いて説明文書を作成する方法の基礎と、 Read The Docs に無料で説明文書をホストしてもらう方法を説明します。

Sphinx をインストールする

pip を使って Sphinx をインストールするには:

Unix/macOS

python3 -m pip install --upgrade sphinx

Windows

py -m pip install --upgrade sphinx

その他のインストール方法については、 Sphinx による インストールガイド を見てください。

Sphinx の初めの第一歩

プロジェクトの中に説明文書を保持するための docs ディレクトリを作成します:

cd /path/to/project
mkdir docs

docs ディレクトリ内で sphinx-quickstart コマンドを実行します:

cd docs
sphinx-quickstart

これは、ソースディレクトリを作成し、いくつかの基本的な設定事項を渉猟し、 conf.py ファイルと同様に index.rst ファイルを生成します。

index.rst にプロジェクトに関する情報をいくらか追加して、ビルドします:

make html

ビルドのプロセスに関するもっと詳しいことは、 Read The Docs の ガイド を見てください。

他の情報源

Sphinx と reStructuredText の使い方に関するもっと詳細なガイドについては、 Python のためのヒッチハイカーズガイドの中の 説明文書を作るチュートリアル を見てください。