このドキュメントでは、チュートリアル形式で、Sphinxを使ってよく行うタスクについての概要を紹介していきます。
緑色の矢印は、説明しているタスクについての発展的な内容がリンク先に掲載されていることを示しています。
ドキュメントのソースが含まれているディレクトリのルートは ソースディレクトリ と呼ばれます。このディレクトリには、Sphinxの設定ファイル conf.py があり、Sphinxがどのようにソースを読み込んで出力するのか、というすべての設定がここに書かれています。 [1]
Sphinxの最初の第一歩は sphinx-quickstart と呼ばれるプログラムを実行し、ソースディレクトリを作成して、いくつかの質問に答えながら、一般的な設定が既に書かれているデフォルトの conf.py を生成するところから始まります。次のようにタイプします:
$ sphinx-quickstart
いくつかの質問が行われます。ここでは最低限”autodoc”拡張に関する質問だけはYESと回答しておいてください。
もう sphinx-quickstart は実行しましたね？ conf.py と、マスタードキュメントの index.rst (もしデフォルトで作成した場合)が含まれる、ソースディレクトリができています。 マスタードキュメント の主な役割は、トップページを提供し、TOCツリー(索引のツリー、もしくは toctree)のルートが置かれています。このTOCツリーというのは、SphinxがreStructuredTextに追加した主要な要素の一つで、複数のファイルを単一の階層構造に結びつける役割を持っています。
最初に生成されたときは、toctreeディレクティブは次のようになっています:
.. toctree::
:maxdepth: 2
ディレクティブの コンテンツ のところにドキュメントのリストを追加します:
.. toctree::
:maxdepth: 2
intro
tutorial
...
これは、このドキュメントの目次がどのように見えるのか、というのとまったく同じです。ここに含めるドキュメントは、 ドキュメント名 を使って追加します。簡単に説明すると、拡張子を取り、ディレクトリの記号にスラッシュ(/)を利用した物です。
さらに詳しい情報については、 toctreeディレクティブ をご覧下さい。
次に、toctreeに追加したファイルを作成し、内容を書くことができるようになりました。”maxdepth”で指定された階層まで、toctreeディレクティブの書かれた場所に、リストされたドキュメントのセクションタイトルとリンクが挿入され、目次ができあがります。Sphinxはこのディレクティブを通じて、ドキュメントの階層と順番を知ります。子供の文章の中にも toctree ディレクティブを書くことができるため、必要であれば深い階層構造を作ることもできます。
Sphinxのソースファイルの中では、標準のreStructuredTextの機能をほとんどそのまま利用することができます。また、Sphinxによっていくつかの機能が追加されています。例えば、 ref を使用した、移植可能（すべての出力形式で動作する)な相互ファイル参照を追加することもできます。
例えば、HTMLバージョンの出力を見ているとすると、サイドバーにある”ソースを見る”というリンクを使用すると、ドキュメントのソースを見ることができます。
reStructuredTextのより詳しい説明については、 reStructuredText入門 をご覧下さい。また、Sphinxが追加したマークアップの完全なリストは Sphinxマークアップ集 を見ると書かれています。
今、いくつかのファイルとコンテンツを追加したとしましょう。それではドキュメントをビルドしてみましょう。ビルドするには sphinx-build プログラムを使用します。次のように実行します:
$ sphinx-build -b html ソースディレクトリ ビルドディレクトリ
ソースディレクトリ は ソースディレクトリ を、 ビルドディレクトリ はビルドされたドキュメントが置かれるディレクトリを意味します。 -b オプションを使用すると、ビルダーを選択することができます。このサンプルではHTMLファイルを出力するビルダーを選択しています。
sphinx-build がサポートする完全なオプションは、 sphinx-buildの起動 を参照してください。
しかし、 sphinx-quickstart スクリプトは Makefile と make.bat を生成するため、作業はもっと簡単です。次のように実行するだけで、選択したビルドディレクトリの中にHTMLをビルドすることができます:
$ make html
選択できるターゲットを見るためには、オプションを指定しないで make を実行してみてください。
Sphinxの主な目的にの一つが、簡単に ドメイン に属する オブジェクト (非常に一般的な意味です)のドキュメントを書けるようにする、というものです。ドメインというのはお互いに関連する、オブジェクトの型を集めた物です。オブジェクトの説明を作成したり、参照したりすることができます。
もっとも使用されるドメインは、Pythonドメインです。Pythonの組み込み関数の enumerate() のドキュメントを書く場合には、作成しているソースに次のように書き加えます:
.. py:function:: enumerate(sequence[, start=0])
*sequence* の要素と、そのインデックスのタプルを生成するイテレータを返します(....など)
これは次のようにレンダリングされます:
- enumerate(sequence[, start=0])¶
sequence の要素と、そのインデックスのタプルを生成するイテレータを返します(....など)
ディレクティブの引数は、説明したいオブジェクトの signature です。コンテンツには、それに対するドキュメントそのものを書きます。複数のシグネチャを、1行ごとに書くこともできます。
Pythonドメインはデフォルトのドメインとなるので、それに関する設定を変更していない限りは、次のようにドメインを指定するプリフィックスを付けずに書いても、同じ結果となります:
.. function:: enumerate(sequence[, start=0])
...
これ以外にも、 py:class, py:method など、Pythonの他のオブジェクトの種類のドキュメントを書くためのディレクティブがいくつも定義されています。また、これらのオブジェクトの型ごとに、相互参照を行うための role も定義されています。このマークアップを記述すると、 enumerate() のドキュメントへのリンクが作成されます:
この :py:func:`enumerate` 関数は、・・・という目的で使用することができ・・・
実際に試してみたのがこれです: enumerate()
繰り返しになりますが、Pythonのドメインがデフォルトで設定されている場合には py: という接頭辞を外して書くこともできます。また、その enumerate() の実際のドキュメントが、どのファイルに書かれているのか、ということを気にする必要はありません。Sphinxが自動で見つけてリンクを張ってくれます。
ドメインごとに、シグニチャをどのように見せることができるのか、というルールは変わってくるでしょう。フォーマットをどのようにきれいに整えたり、C/C++ドメインのように引数の型にリンクを張るなどの言語ごとの特別な機能が追加されることもあります。
使用できるすべてのドメインと、それらのディレクティブ/ロールについて知りたい場合には、 Sphinxドメイン を参照してください。
最初の方で、Sphinxがドキュメントをどのように処理するのかを制御する、 conf.py というファイルがあるということについては軽く紹介しました。このファイルはPythonのソースファイルとして実行され、中に設定値を記述することができます。上級のユーザは、Sphinxが処理をする際に、 sys.path を拡張したり、ドキュメントの記述するバージョン番号を取得してくるために、製品コードをインポートして情報を得るような、いくつかの処理を実装するでしょう。
おそらく多くのユーザが変更したがると思われるような設定値については、 sphinx-quickstart を通じて、 conf.py に既に書き込まれ、最初はコメントアウトされた状態になっています(Pythonの標準的な文法で、 # を書くと行の残りの内容がコメントになる)。デフォルト値を変更する場合には、 # 記号を削除して、値を変更してください。 sphinx-quickstart が自動的に追加しない設定値については、設定行を追加してください。
Pythonの文字列、数値、リストなどの文法を利用して設定ファイルを書く必要があります。設定ファイルは、最初の行のエンコーディング宣言の通り、デフォルトではUTF-8形式で保存されます。文字列の値として、非アスキー文字をしようしたい場合には、Pythonのユニコード文字列(例: project = u'日本語版Expose')を使用する必要があります。
すべての使用可能な設定値については、 ビルド設定ファイル のドキュメントを参照してください。
もしもPythonで書かれたコードのドキュメントを書こうとしている場合には、docstring形式でソースファイル中に既に多くのドキュメントを書いているでしょう。Sphinxは “autodoc” という 拡張機能 を利用することでソースファイルからdocstringを抽出してくて文章に取り込むというのをサポートしています。拡張機能はPythonで書かれたモジュールで、Sphinxのプロジェクトに様々な機能を付加します。
autodocを使用するためには、 conf.py の extensions という設定値に 'sphinx.ext.autodoc' という文字列を追加して、この機能を有効化する必要があります。追加すると、いくつかのディレクティブがプロジェクトに追加されます。
例えば、 io.open() という関数に関するドキュメントであれば、次のように記述すると、シグネチャやdocstring情報はソースファイルから読み取ります:
.. autofunction:: io.open
autodoc関連のディレクティブのmembersオプションを利用すると、クラスやモジュールの要素のドキュメントを自動的に作成することもできます:
.. automodule:: io
:members:
autodocはモジュールをインポートしてdocstringの情報を収集する必要があります。そのため、ドキュメント対象のモジュールを読み込むために、 conf.py の中で、適切なパスを sys.path に追加する必要があります。
autodoc機能の完全な説明は、 sphinx.ext.autodoc の説明を参照してください。
脚注
| [1] | これは基本的なレイアウトです。しかし、 conf.py を 設定ディレクトリ と呼ばれる他の場所に置くこともできます。詳しくは sphinx-buildの起動 をご覧下さい。 |