はじめに¶

プロジェクトと開発環境の設定¶

新しいディレクトリを作成し、README.rst という名前のファイルを作成して、次の内容を記述します。

README.rst¶

Lumache
=======

**Lumache** (/lu'make/) is a Python library for cooks and food lovers that
creates recipes mixing random ingredients.

ここで、Python 仮想環境を作成し、必要なツールをインストールすることをお勧めします。そのためには、コマンドラインターミナルを開き、作成したディレクトリに cd し、次のコマンドを実行します。

$ python -m venv .venv
$ source .venv/bin/activate
(.venv) $ python -m pip install sphinx

注記

上記で使用されているインストール方法は、PyPI パッケージでより詳細に説明されています。このチュートリアルの残りの部分では、Python 仮想環境を使用することを前提として説明します。

これらの手順を正しく実行した場合は、Sphinx コマンドラインツールが利用できるはずです。次のコマンドを実行して、基本的な検証を行うことができます。

(.venv) $ sphinx-build --version
sphinx-build 4.0.2

同様の出力が表示された場合は、正しい手順で進んでいます！

次に、コマンドラインから次のコマンドを実行します。

(.venv) $ sphinx-quickstart docs

これにより、docs フォルダー内にプロジェクトの基本的なディレクトリと設定レイアウトを作成するために必要な一連の質問が表示されます。続行するには、各質問に次のように答えます。

> Separate source and build directories (y/n) [n]：「y」(引用符なし)と入力し、Enterを押します。
> Project name：「Lumache」(引用符なし)と入力し、Enterを押します。
> Author name(s)：「Graziella」(引用符なし)と入力し、Enterを押します。
> Project release []：「0.1」(引用符なし)と入力し、Enterを押します。
> Project language [en]：空欄のままにして(デフォルトの英語)、Enterを押します。

最後の質問の後、次の内容を含む新しいdocsディレクトリが表示されます。

docs
├── build
├── make.bat
├── Makefile
└── source
   ├── conf.py
   ├── index.rst
   ├── _static
   └── _templates

これらのファイルの目的は次のとおりです。

build/: (現時点では)レンダリングされたドキュメントを格納する空のディレクトリです。
make.bat と Makefile: コンテンツのレンダリングなど、一般的な Sphinx 操作を簡素化する便利なスクリプトです。
source/conf.py: Sphinx プロジェクトの設定を保持する Python スクリプトです。 sphinx-quickstart に指定したプロジェクト名とリリースに加えて、いくつかの追加の設定キーが含まれています。
source/index.rst: プロジェクトのルートドキュメントであり、ウェルカムページとして機能し、「目次ツリー」(または *toctree*) のルートを含みます。

このブートストラップ手順のおかげで、ドキュメントを初めて HTML としてレンダリングするために必要なものがすべて揃っています。そのためには、次のコマンドを実行します。

(.venv) $ sphinx-build -M html docs/source/ docs/build/

最後に、ブラウザでdocs/build/html/index.htmlを開きます。次のようなものが見えるはずです。

できました！Sphinx を使用して最初の HTML ドキュメントを作成しました。これで、カスタマイズを開始できます。