説明文書を作成する¶
この節では、 Sphinx を用いて説明文書を作成する方法の基礎と、 Read The Docs に無料で説明文書をホストしてもらう方法を説明します。
Sphinx をインストールする¶
pip
を使って Sphinx をインストールするには:
python3 -m pip install --upgrade sphinx
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 のためのヒッチハイカーズガイドの中の 説明文書を作るチュートリアル を見てください。