Sphinxは、Docutilsを拡張して実装されたドキュメント作成ソフトで、reStructuredText（以下 reST）で書かれたテキストファイルをHTMLやPDFで出力できます。
Sphinxを使いこなすためには、reSTの書き方を覚え、コマンドライン操作が必要になります。また、画像を複雑にレイアウトするような文書には適していません。
とりあえず、何も内容を書かずに、プロジェクトの作成とHTMの出力まで試します。
手順は以下の3つです。
- インストール
- プロジェクトフォルダとプロジェクトの作成
- HTMLファイルの作成
インストールはpipコマンドを使えば簡単です。画像処理用にPillowもインストールしておくとよいようです。
pip install sphinx Pillowインストールが終わったら、プロジェクト用フォルダを作成し、そのフォルダのアドレスバーに「cmd」と入力してエンターを押すと、そのフォルダをカレントフォルダとしてコマンドプロンプトが起動します。
プロンプトでSphinxと同時にインストールされるsphinx-quickstartを引数なしで実行して下記の質問に答えます。「Project name」と「Author name(s)」は必須で、言語は「ja」を指定。その他は特に入力は必要ありません。
| 質問 | 意味 |
|---|---|
| Separate source and build directories (y/n) [n]: | 出力フォルダを分けるか |
| Project name: | プロジェクト名 |
| Author name(s): | 作成者 |
| Project release []: | リリース番号 |
| Project language [en]: | 言語 |
実行後、フォルダには以下のファイルが作成されます。質問の答えは、conf.pyに反映されているので、変更があったら書き換えられます。
| ファイル（フォルダ） | 役割 |
|---|---|
| conf.py | ビルド設定ファイル |
| index.rst | reST原稿のひな型 |
| make.bat | ビルドスクリプト（Window用） |
| Makefile | ビルドスクリプト（その他の環境） |
| _build/ | 成果物出力フォルダ |
| _static/ | 静的ファイルを置くフォルダ |
| _templates/ | HTMLテンプレート用フォルダ |
続けて、コマンドプロンプトで「make html」と打ち込むと、最初の質問で変更していなければ、プロジェクト用フォルダ内の「_build\html」内に「index.html」が作成されています。ファイルを開き、下図のようにプロジェクト名や作成者が反映されたHTMLが作成されていることを確認します。
あとはプロジェクトフォルダに作成された「index.rst」をreSTの記法に従って編集していきます。
reSTの記法については、Sphinxでの文章の書き方(reStructuredText)がよくまとまっていてわかりやすいと思います。
reSTで特徴的なのは、ディレクティブというreST記法を拡張する仕組みです。これは、以下のような構造で、ディレクティブ名に応じて様々な役割を果たします。
.. ディレクティブ名:: オプション
:引数:
:パラメータ付き引数: パラメータ
コンテンツ
例えば、index.rstで文書構造を定義するTOCツリーディレクティブを使うと、index.rstを目次として、文書を複数のファイルに分割することができます。ファイルパスは、プロジェクトフォルダの直下がルートです。例えば、「rst」フォルダに分割したファイルを作成した場合は、以下のような指定をします。ファイルパスを指定するときのフォルダ区切りは、「\」だと上手く読み込めないことがあるので「\」を重ねてエスケープするか、スラッシュ（/）を使います。
.. toctree::
rst/file-a
rst/file-b
rst/file-c
この他にもコードブロックディレクティブや画像ディレクティブなど数多くのディレクティブが用意されています。reStructuredText ディレクティブにの詳細が記載されています。
参考
ネット情報は、何となく読み流してしまったり、複数のサイトで違う内容が書かれていたりして、体系的に学ぶには、やはり書籍が分かりやすいと感じます。
結局、多すぎるネット情報に困惑した結果、オライリーで直販または電子書籍で販売となっているこちらの書籍を購入しました。
Sphinxそのものの説明から具体例・付録のreSTリファレンスまで、非常に分かりやすくまとまっていて、とても助かりました。