プロジェクトを作る

Sphinxでドキュメントを作成するためには、まず「プロジェクト」を作る必要があります。プロジェクトはコマンドラインで作成しますので、Windowsの場合はコマンドプロンプト、MacやLinuxの場合はTerminal(仮想端末)を起動させます。

プロジェクトは、いくつかの設定ファイルなどが配置された、ドキュメントを保存するための専用ディレクトリです。配置するファイルなどは、Sphinxに含まれる「sphinx-quickstart」というコマンドで作成します。

sphinx-quickstart

何もオプションを付けないと対話モードになり、 -q オプションを付けると非対話モードでプロジェクトが作成できます。ここでは非対話モードを紹介します。

プロジェクト名の指定:

-p

ドキュメントの製作者(Author name(s))の指定:

-a

プロジェクトのバージョンを指定:

-v

プロジェクトのロケール(言語)を指定:

-l

引数の最後にプロジェクトのディレクトリ名を指定しますが、下記に注意してください。

  • プロジェクトは引数で指定されたディレクトリに作成されます。

  • 指定されたディレクトリが存在しない場合は、ディレクトリが作成されます。

  • 省略されている場合はカレントディレクトリとなります。

  • プロジェクトを作成するディレクトリは空の必要があります。

今回は、自分の書評ページなので、プロジェクト名は "Book Review" 、バージョン番号は 1.0 、著者名には自分の名前を入れます。

sphinx-quickstart(非対話モード)の実行例:

$ sphinx-quickstart -q -p "Book Review" -a sphinx-users.jp -v 1.0 -l ja project_dir
Creating file project_dir/conf.py.
Creating file project_dir/index.rst.
Creating file project_dir/Makefile.
Creating file project_dir/make.bat.

Finished: An initial directory structure has been created.
(... 以下省略 ...)

ページ構成を作っていこう

ひな形ができたので、次にページを足して、ドキュメントを作成していきます。ここでは上記の質問で、ディレクトリ設定に関してはデフォルト(ソースとビルドを分けない、プリフィックスは _)であるとします。

"Expert Python Programming"と、"The Art of Community"という本を紹介したいとします。それぞれ、1ファイルに書くことにして、以下の様なページ構成にします:

index.rst
  +- expert_python.rst
  +- art_of_community.rst

Sphinxでドキュメントを書く場合には、何種類かのディレクティブ(命令)をドキュメントの中に入れていきますが、その中でも一番重要なディレクティブが .. toctree:: です。これは、文章の親子関係を定義するディレクティブです。マスタードキュメントである、 index.rst には既にこのディレクティブがありますので、そこに項目を追加します。なお、このファイルの先頭数行はコメントですので、省略してあります。

index.rst:

 1Welcome to Book Review's documentation!
 2=======================================
 3
 4Contents:
 5
 6.. toctree::
 7   :maxdepth: 2
 8
 9   expert_python
10   art_of_community
11
12Indices and tables
13==================
14
15* :ref:`genindex`
16* :ref:`modindex`
17* :ref:`search`

注釈

:maxdepth: と、ファイル名(拡張子無し)のリストの間には空行を入れましょう。

それでは、子供のファイルも作ってみましょう。なお、日本語を入力する場合、文字コードはUTF-8エンコードにします。

expert_python.rst:

 1=========================
 2Expert Python Programming
 3=========================
 4
 5:著者: Tarek
 6:出版社: Packt Publishing
 7
 8内容
 9====
10
11Pythonのエキスパート向けの本。Pythonの内部のアルゴリズムにも言及しつつ
12マニアックな文法の適切な使い方の紹介に始まり、アジャイルソフトウェア開発
13をPythonで行うためのテストツール、継続的インテグレーションのツールなどの
14紹介や、よりよいプログラムのための、Pythonのためのデザインパターン、
15パフォーマンスチューニングなど、幅広く、深い内容の本。

art_of_community.rst:

 1====================
 2The Art of Community
 3====================
 4
 5:著者: Jono Bacon(Ubuntu Linuxのコミュニティマネージャ)
 6:出版社: O'reilly
 7
 8内容
 9====
10
11コミュニティの運営について幅広く書かれた本。コミュニティの作り方、
12コミュニティ運営に役立つツール、コミュニティの測定方法、管理組織など、
13超巨大なコミュニティ運営にも耐えうる方法論が展開される一方、
14Buzzの作り方、物理イベントや、オンラインイベントの開催方法、
15ケンカの仲裁の仕方、スポンサーの集め方にいたるまで、経験に裏打ちされた
16様々なトピックが並ぶ。

ファイルができたら、下記のコマンドを実行して、HTMLファイルを作ってみましょう。

$ make html

_build/html フォルダ内にHTMLが生成されます。おめでとうございます！これがSphinxで生成したドキュメントになります。

HTMLを見ると、ページのタイトルがtoctreeディレクティブのあるところに子供のページのタイトルが表示されていることが分かります。次は、このメカニズムを見ていきます。Sphinxで一番重要なのが、このtoctreeの仕組みを知ることです。

../_images/html_result.jpg

toctreeの仕組み

Sphinxのすべてのページにはセクションタイトルが含まれます。

先に挙げた、3つの例では、セクションのタイトルとして、 = 記号を使っていることが分かります。Sphinxでは、 #, *, =, -, ^, ~, " などの記号を使うことができます。記号は上下に記号を並べる方式と、アンダーラインのようにする方式の2つがあります。記号の種類と書き方(上下、下のみ)で色々なフォーマットが実現できますが、1つのファイル内の登場順で、レベルが決まり、階層化されます。上記のサンプルでは、子供ファイルのタイトル(= の上下)がレベル1, 内容と書かれている部分(= の下だけ)がレベル2になります。

toctreeディレクティブは、子供のセクションタイトル情報を持ってきて、目次を作ります。ここでは maxdepth オプションが2なので、レベル2までのタイトルを持ってきます。この仕組みのおかげで、ある程度の深さを持ったドキュメントであっても、見通しが良くなり、情報が探しやすくなります。

また、toctreeは1ページにいくつも書くことができます。また、toctreeが書かれている場所のセクションタイトルのレベルの影響も受けます。toctreeの位置のセクションタイトルのレベルが2であれば、子供のドキュメントのレベル1, レベル2のセクションタイトルは、親ドキュメントのレベル3, レベル4相当として扱われます。以下の図がこれを説明したサンプルです。このドキュメント全体を maxdepth 2 としてtoctreeで子供に設定すると、孫のレベル1のタイトルを含め、赤字のタイトルまでが取り込まれることになります。

../_images/toctree.png

注釈

セクションタイトルがないファイルは、警告が表示されます。

それでは、次に、 Sphinxのドキュメントをパワーアップさせる、各種マークアップやディレクティブを紹介します。