はじめに

Sphinx は、開発者がドキュメントをプレーン・テキストで作成し、その出力をさまざまなニーズに対応した多様なフォーマットで容易に生成するためのツールです。Sphinx は、バージョン管理システムを使用して変更を追跡する場合にも役に立ちます。プレーン・テキストのドキュメントは異なるシステム間で協力作業を行う場合にも便利です。プレーン・テキストは現在利用可能なフォーマットのうち、最も移植の容易なフォーマットの 1 つです。

Sphinx は Python で作成されており、元々は Python 言語のドキュメント作成用に作られたものですが、必ずしもドキュメント作成の対象言語を Python のみに限定しているわけではありません。場合によってはプログラマーの作成するドキュメントのみが対象というわけですらありません。Sphinx の利用者は数多くおり、本をまるごと Sphinx で執筆する人もいます。

Sphinx はドキュメント作成フレームワークと考えることができます。つまり Sphinx は、単調で面倒な作業の部分を抽象化し、一般的な問題を解決するための自動機能を提供します (例えば見出しの索引化や、(コード例を表示する場合に) 適切な構文強調機能によって特別なコードを強調表示する機能など)。

要件

Sphinx の操作は基本的にコマンドライン・インターフェースで行うため、Linux や UNIX のターミナル・ソフト (コンソール、あるいはターミナル・エミュレーターと呼ばれることもあります) を十分に使いこなせる必要があります。

Python をインストールしておく必要があります。主な Linux ディストリビューションのすべて、またUNIX ベースの一部のオペレーティング・システム (Mac OSX など) にも Python がプリインストールされており、そのまま使用できるようになっています。Sphinx は Python のバージョン 2.4、2.5、2.6 で動作するはずです。Python の有効なバージョンがインストールされていることを確認するには、リスト 1 のコマンドを実行してください。

$ python --version
Python 2.6.1

構文

Sphinx は reStructuredText マークアップ構文を使用して文書を制御します (ただし他の構文も使用します)。プレーン・テキストのファイルを作成したことがある人であれば、Sphinx を使いこなすために必要な構文についても、おそらく既にかなりよく理解しているはずです。

reStructuredText マークアップにより、テキストを定義して構造を指定し、適切なフォーマットで出力することができます。詳細に入る前に、リスト 2 に示す簡単なマークアップ構文の例を見てください。

This is a Title
===============
That has a paragraph about a main subject and is set when the '='
is at least the same length of the title itself.

Subject Subtitle
----------------
Subtitles are set with '-' and are required to have the same length 
of the subtitle itself, just like titles.

Lists can be unnumbered like:

 * Item Foo
 * Item Bar

Or automatically numbered:

 #. Item 1
 #. Item 2

Inline Markup
-------------
Words can have *emphasis in italics* or be **bold** and you can define
code samples with back quotes, like when you talk about a command: ``sudo`` 
gives you super user powers! 

これを見るとわかるように、この構文はプレーン・テキストで非常に読みやすくなっています。特定のフォーマット (HTML など) を作成する段階になると、タイトルは大見出しらしくなり、(当然ながら) サブタイトルよりもフォントは大きくなり、番号付きリストには適切に番号が付けられます。この段階でも、非常に強力な機能が既に実現されています。番号付きリストへの項目追加や順序変更によって番号の付け方は影響されず、またタイトルに使用する下線を置き換えることでタイトルの重要度を変更することができます。

インストールと構成

インストールはコマンドラインで行い、その方法はリスト 3 に示すように簡単です。

$ easy_install sphinx
Searching for sphinx
Reading http://pypi.python.org/simple/sphinx/
Reading http://sphinx.pocoo.org/
Best match: Sphinx 1.0.5
Downloading http://pypi.python.org/packages/[...]
Processing Sphinx-1.0.5-py2.5.egg
[...]
Finished processing dependencies for sphinx

リスト 3 は簡単のため、省略して一部のみを載せていますが、これを見れば Sphinx のインストールに必要な操作を理解できることと思います。

Sphinx はディレクトリー構造を使用することによってソース (プレーン・テキスト・ファイル) とビルド (生成された出力のこと) との分離をある程度実現しています。例えば、ドキュメント・ソースから PDF を生成するように Sphinx に指示すると、生成されたファイルはビルド・ディレクトリーに配置されます。この動作は変更可能ですが、ここでは一貫性を持たせるためにデフォルトの形式に従うことにします。

では早速、sphinx-quickstart を実行して新しいドキュメント作成プロジェクトを開始しましょう。リスト 4 のように何項目かの入力を促されます。Enter を入力し、デフォルト値をすべて受け入れます。

$ sphinx-quickstart 
Welcome to the Sphinx 1.0.5 quickstart utility.

Please enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).
[...]

プロジェクトには「My Project」という名前を付けました。この名前は何ヶ所かで参照されます。もちろん、他の名前を付けても構いません。

sphinx-quickstart コマンドを実行すると、作業ディレクトリーのファイルはリスト 5 のようになるはずです。

.
├── Makefile
├── _build
├── _static
├── conf.py
└── index.rst

では各ファイルを詳細に調べてみましょう。

• Makefile: コードをコンパイルしたことがある人には、このファイルはおなじみのはずです。コンパイルの経験がない人は、make コマンドを使用してドキュメント出力をビルドする際の命令を含むファイルと考えてください。
• _build: 特定の出力がトリガーされた後、生成されたファイルはこのディレクトリーに配置されます。
• _static: ソース・コードに含まれないファイル (画像など) はすべてここに配置され、それらは後でビルド・ディレクトリーの中でリンクされます。
• conf.py: Sphinx を構成する値を保持する Python ファイルであり、ターミナル・ソフトで sphinx-quickstart を実行したときに選択された値も、このファイルの中に含まれています。
• index.rst: ドキュメント作成プロジェクトのルートです。ドキュメントが他のファイルに分割されている場合には、それらのファイルはこの index.rst ファイルによって接続されます。

Sphinx を使い始める

ここまでの段階で、Sphinx を適切にインストールし、デフォルトの構造を理解し、基本的な構文を理解しました。しかし、すぐにドキュメントの作成を始めたりせず、十分に注意して取り組む必要があります。レイアウトや出力について理解していないと、間違えやすく、またプロセス全体に非常に時間がかかってしまう可能性があるからです。

index.rst の中を見てください。この中には大量の情報があり、それ以外にも、複雑な構文が多少あります。作業を容易にし、混乱を避けるために、新しいファイルをメイン・セクションのリストに記載することで、そのファイルが組み込まれるようにします。

index.rst ファイルのメイン・タイトルの直後に、toctree 宣言を使用したコンテンツ・リストがあります。toctree はすべてのドキュメントをまとめて 1 つのドキュメントにするための中心要素です。たとえファイルが存在していても、toctree の配下に記述がなければ、それらのファイルはドキュメントをビルドする際の生成対象にはなりません。

ここでは新しいファイルをドキュメントに追加し、そのファイルの名前を example.rst にします。このファイルを toctree 配下のファイル・リストに含める必要がありますが、その際には注意が必要です。toctree のファイル・リストが機能するためには空白に関する規則に従う必要があり、またファイル拡張子 (この場合は .rst) は必要ありません。リスト 6 はこのファイル・リストの構造を示しています。左マージンとファイル名との間に空白が 3 つ必要であり、また maxdepth オプションの後に 1 行の空白行が必要です。

Contents:

.. toctree::
   :maxdepth: 2

   example

この時点では他のオプションを気にする必要はありません。この段階では、インデックス・ファイルがあり、その中には有効な文書を保持する個々のファイルのリストが含まれること、そしてこのファイル・リストが機能するために特定の順序と空白に従っていることに注意してください。

リスト 2 の構文の例を思い出してください。その例をコピーして example.rst ファイルに貼り付け、保存します。これで出力を生成する準備が整いました。

make コマンドを実行し、出力として HTML を指定します。この出力には、JavaScript や CSS ファイルなど、あらゆるものが生成されて含まれているため、この出力を直接 Web サイトとして使用することができます。リスト 7 を見てください。

$ make html
sphinx-build -b html -d _build/doctrees   . _build/html
Making output directory...
Running Sphinx v1.0.5
loading pickled environment... not yet created
building [html]: targets for 2 source files that are out of date
updating environment: 2 added, 0 changed, 0 removed
reading sources... [100%] index
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] index 
writing additional files... genindex search
copying static files... done
dumping search index... done
dumping object inventory... done
build succeeded.

Build finished. The HTML pages are in _build/html.

make コマンドの他のオプションに関心がある人はリスト 8 を見てください。リスト 8 は、make コマンドに help フラグを渡すことで、make コマンドの完全な説明を表示させる方法を示しています。

$ make -h
Usage: make [options] [target] ...
Options:
[...]  

静的な文書を作成する

最初の例として、2 つのファイルから HTML を生成すると、フル機能の (静的な) Web サイトが出来上がります。

_build ディレクトリーの中に、doctrees と HTML という 2 つの新しいディレクトリーが作成されているはずです。ここで関心の対象となるのは HTML ディレクトリーです。このディレクトリーはドキュメントのサイトに必要なすべてのファイルを保持しています。ブラウザーで index.html ファイルを開くと、図 1 のような内容が表示されるはずです。

ごくわずかな情報から、Sphinx は大量の内容を作成することができています。基本的なレイアウトが用意されており、その中にはプロジェクトのドキュメントに関する情報、検索セクション、目次、名前と日付を含む著作権情報、そしてページ機能が含まれています。

検索セクションは注目に値します。なぜなら、すべてのファイルが Sphinx によって索引付けされ、検索機能付きの静的サイトが JavaScript の魔術によって作成されているからです。

リスト 6 で、ドキュメント作成用の別ファイルとして toctree に example を追加したことを思い出してください。画面を見ると、「Content (目次)」の項目としてメイン・タイトルが箇条書きの最上位レベルに表示され、サブタイトルが 2 番目のレベルに表示されていることがわかります。適切な構造になるように、Sphinx がすべての処理をしてくれたのです。

すべてのリンクはドキュメント内の適切な場所を指しており、またタイトルとサブタイトルにはアンカーがあり、そのアンカーによって該当部分と直接リンクすることができます。例えば、「Subject Subtitle」セクションにはマウス・オーバーによってブラウザーに ../example.html#subject-subtitle のように表示されるアンカーがあります。先ほど触れたように、Sphinx を使用することで、こうした些細な作業の繰り返しについて気にする必要がなくなります。

図 2 は example.rst を静的サイトの HTML ファイルとして表示した場合を示しています。

グラフィックを作成する

プロジェクトのドキュメントへの関心を高め、ドキュメントを読みやすくする上で、短く簡潔な段落、画像、グラフはどれも重要です。Sphinx を使用すると静的なファイルを容易に追加することができるため、これらの重要な要素によって読者の注意を引きつけることができます。

静的ファイルを追加するための適切な構文は簡単に覚えることができます。Sphinx がドキュメントのレイアウトを作成した時に作成した _static ディレクトリーに静的ファイルを配置するだけで、それらのファイルを問題なく参照することができるはずです。リスト 9 で、reStructuredText ファイルの中ではその対象とする参照ファイルがどのように記述されているかを見てください。この場合は example.rst の最後に静的ファイルに関する記述を追加しています。

.. image:: _static/system_activity.jpg

ドキュメントを再度生成すると、システムのアクティビティーに関する小さな JPEG グラフについて、パスを指定したとおりの場所に画像が適切に配置されるはずです。このグラフは図 3 のように表示されるはずです。

まとめ

この記事では Sphinx を使い始めるための基本事項について説明しましたが、他にも興味深い部分はたくさんあります。Sphinx は多様なフォーマットでドキュメントをエクスポートすることができますが、そのためにはライブラリーやソフトウェアを追加でインストールする必要があります。生成できるフォーマットには、PDF、EPUB、man (UNIX マニュアル・ページ)、LaTeX などがあります。

複雑なグラフのために、ドキュメント作成プロジェクトに Graphviz グラフを追加するプラグインがあります。私はかつて、職場の簡単なネットワーク・マップの図を作成する必要に迫られたことがあります。その際、別のツールを使わなくても、すべてを同じドキュメント内で作成できるのは便利なことでした。Graphviz プラグインと同様、Sphinx に使用できるプラグイン (拡張機能とも呼ばれます) はたくさんあります。一部のプラグインは Sphinx に含まれています (さまざまな Sphinx プロジェクトをリンクさせることができる interSphinx など)。

生成された出力のルック・アンド・フィールが気に入らない場合のために、Sphinx には多くのテーマが含まれており、それらのテーマを適用することによって HTML ファイルによるドキュメントの描画方法を大幅に変更することができます。Celery や Lettuce など、一部の重要なオープンソース・プロジェクトでは、CSS の変更とテンプレートの拡張によって HTML を表示したときの見た目を大幅に変更しています。これらのプロジェクトへのリンク、またデフォルトの CSS やレイアウトの拡張方法や変更方法を説明したドキュメントへのリンクは「参考文献」を参照してください。

Sphinx により、私はドキュメント作成に関する考え方が変わりました。私の個人的なオープンソース・プロジェクトのほぼすべて、そして何件かの社内プロジェクトのドキュメント作成が Sphinx によって容易になることを理解できると、退屈であったドキュメント作成が興奮に満ちた作業に変わりました。皆さんのドキュメント作成作業に Sphinx を活用し、忘れ去られた情報を容易に取り出してください。

上に戻る

ダウンロード

ダウンロード形式について

参考文献

学ぶために

• Sphinx プロジェクトのドキュメントを調べてください。
  
  
• Sphinx 拡張: 拡張機能の完全な一覧、そしてサードパーティーによる拡張機能の外部参照資料が網羅されています。
  
  
• HTMLテーマのサポート: このセクションには現在のテーマの拡張方法や新しいテーマの適用方法が説明されています。
  
  
• Celery プロジェクトのドキュメントは Sphinx を使用してデフォルトの CSS やフォントの値を変更しています。
  
  
• Python プログラミング言語のドキュメント: Sphinx は Python に関する完全なドキュメントを作成するために作成されたものです。
  
  
• Lettuce も、Sphinx が生成する HTML を (大幅に) 変更しているオープンソース・プロジェクトです。
  
  
• システム構成エンジン、Pacha は私のオープンソース・プロジェクトの 1 つであり、このプロジェクトでは Sphinx を使用しています。
  
  
• developerWorks の Open source ゾーン: オープンソース技術を使用した開発や、IBM 製品でオープンソース技術を使用するためのハウ・ツー情報やツール、プロジェクトの更新情報など、豊富な情報が用意されています。
  
  
• 関心のあるイベント: IBM オープンソース開発者にとって関心のある、今後開催されるカンファレンスや業界展示会、ウェブキャスト、その他のイベントについて調べてみてください。
  
  
• developerWorks podcasts: ソフトウェア開発者のための興味深いインタビューや議論を聞いてください。
  
  
• developerWorks On demand demos: IBM とオープンソース技術、製品機能について学ぶために、無料のデモをご覧ください。
  
  
• developerWorks on Twitter: developerWorks の最新ニュースをフォローしてください。
  
  

製品や技術を入手するために

• IBM 製品を評価してください: 無料の試用版のダウンロードからクラウドでホストされる製品に至るまで、開発者のために特に用意されたソフトウェアを利用して皆さんの次のオープンソース開発プロジェクトを革新してください。
  
  

議論するために

• 著者のホームページを訪れ、コメントを書き込み、また著者とやり取りしてください。
  
  
• developerWorks コミュニティー: 開発者向けのブログ、フォーラム、グループ、ウィキなど利用しながら、他の developerWorks ユーザーとやり取りしてください。developerWorks のコミュニティー、Real world open source グループの構築を支援してください。
  
  

著者について

Alfredo Deza はソフトウェア技術者であり、元プロスポーツ選手であり、オリンピック選手であり、システム管理に豊富な経験を持っています。彼はオープンソース・ソフトウェアを熱心に支持し、また地域の技術グループや PyCon などの国際会議で頻繁に講演を行っています。彼は時間のあるときには写真の腕を磨き、またオープンソース・プロジェクトへの貢献を楽しんでいます。

この記事を評価する

コメント

上に戻る

目次

• はじめに
• インストールと構成
• Sphinx を使い始める
• まとめ
• ダウンロード
• 参考文献
• 著者について
• コメント