Sphinxをはじめよう 第3版

3章HTMLに変換してみよう

HTMLは世界でもっとも使われている文書フォーマットのひとつです。 PCやスマートフォンなど、世にある多くのコンピュータにはWebブラウザが搭載されているため、どの端末でも閲覧できると言って良いでしょう。また、配布や公開もしやすいといった特徴もあります。

この章では議事録の作成を題材に、Sphinxでドキュメントを作り、HTMLに変換するまでの一連の流れを紹介します。

3.1　Sphinxによるドキュメント作成の流れ

Sphinxでは プロジェクト という単位でドキュメントを扱います。 プロジェクトは本文となるreSTファイルや画像、設定など、複数のディレクトリやファイルから構成されます。

そのため、Sphinxを使ってドキュメントを作り始めるときは、最初にプロジェクトを作ることになります。 Sphinxではプロジェクトのひな形を生成するツールとして sphinx-quickstart コマンドを提供しています。

プロジェクトを生成したあとは、ドキュメントを書き進めます。 そして、書き進めながら随時ドキュメントをHTMLやPDF形式に ビルド （変換）します。 Sphinxはドキュメントのビルド向けに sphinx-build コマンドとビルドスクリプトを提供しています。

ビルドで生成された成果物を確認して、必要があればさらに執筆とビルドを繰り返します。 このような流れでドキュメントを作成していきます。

この流れを図示すると 図3.1: のようになります。

図3-1: Sphinxによるドキュメント作成の流れ

それでは、このフローの各ステップをなぞりながら、実際にドキュメントを作ってみましょう。

3.2　プロジェクトの作成 ...