Sphinxの最初の一歩

このドキュメントでは、チュートリアル形式で、Sphinxを使ってよく行うタスクについての概要を紹介していきます。

緑色の矢印は、説明しているタスクについての発展的な内容がリンク先に掲載されていることを示しています。

Sphinxのインストール

Sphinxをインストールするには、ディストリビューションパッケージから、もしくは PyPI から可能です。

$ pip install Sphinx

ドキュメントのソースの準備

reStructuredText ドキュメントソースのSphinx ルートディレクトリは ソースディレクトリ と呼びます。また、このディレクトリはSphinxの設定ファイル conf.py を含んでおり、Sphinxによるソースの解釈、ドキュメントのビルドが可能となります。 [1]

Sphinxの最初の第一歩は sphinx-quickstart と呼ばれるプログラムを実行し、ソースディレクトリを作成して、いくつかの質問に答えながら、一般的な設定が既に書かれているデフォルトの conf.py を生成するところから始まります。次のようにタイプします:

$ sphinx-quickstart

いくつかの質問が行われます。ここでは最低限”autodoc”拡張に関する質問だけはYESと回答しておいてください。

sphinx-apidoc という “APIドキュメント”の自動生成機能もあります。 sphinx-apidocの起動 を参照して下さい。

ドキュメント構造の定義

もう sphinx-quickstart は実行しましたね? conf.py と、マスタードキュメントの index.rst (もしデフォルトで作成した場合)が含まれる、ソースディレクトリができています。 マスタードキュメント の主な役割は、トップページを提供し、TOCツリー(索引のツリー、もしくは toctree)のルートが置かれています。このTOCツリーというのは、SphinxがreStructuredTextに追加した主要な要素の一つで、複数のファイルを単一の階層構造に結びつける役割を持っています。

最初に生成されたときは、toctreeディレクティブは次のようになっています:

.. toctree::
   :maxdepth: 2

ディレクティブの コンテンツ のところにドキュメントのリストを追加します:

.. toctree::
   :maxdepth: 2

   intro
   tutorial
   ...

これは、このドキュメントの目次がどのように見えるのか、というのとまったく同じです。ここに含めるドキュメントは、 ドキュメント名 を使って追加します。簡単に説明すると、拡張子を取り、ディレクトリの記号にスラッシュ(/)を利用した物です。

more info さらに詳しい情報については、 toctreeディレクティブ をご覧下さい。

次に、toctreeに追加したファイルを作成し、内容を書くことができるようになりました。”maxdepth”で指定された階層まで、toctreeディレクティブの書かれた場所に、リストされたドキュメントのセクションタイトルとリンクが挿入され、目次ができあがります。Sphinxはこのディレクティブを通じて、ドキュメントの階層と順番を知ります。子供の文章の中にも toctree ディレクティブを書くことができるため、必要であれば深い階層構造を作ることもできます。

コンテンツの追加

Sphinxのソースファイルの中では、標準のreStructuredTextの機能をほとんどそのまま利用できます。また、Sphinxによっていくつかの機能が追加されています。例えば、 ref を使用した、移植可能(すべての出力形式で動作する)な相互ファイル参照も追加できます。

例えば、HTMLバージョンの出力を見ているとすると、サイドバーにある”ソースを見る”というリンクを使用すると、ドキュメントのソースを見ることができます。

more info reStructuredTextのより詳しい説明については、 reStructuredText入門 をご覧下さい。また、Sphinxが追加したマークアップの完全なリストは Sphinxマークアップ集 を見ると書かれています。

ビルドの実行

今、いくつかのファイルとコンテンツを追加したとしましょう。それではドキュメントをビルドしてみましょう。ビルドするには sphinx-build プログラムを使用します。次のように実行します:

$ sphinx-build -b html sourcedir builddir

ソースディレクトリソースディレクトリ を、 ビルドディレクトリ はビルドされたドキュメントが置かれるディレクトリを意味します。 -b オプションを使用すると、ビルダーを選択することができます。このサンプルではHTMLファイルを出力するビルダーを選択しています。

more info sphinx-build がサポートする完全なオプションは、 sphinx-quickstartの起動 を参照してください。

しかし、 sphinx-quickstart スクリプトは Makefilemake.bat を生成するため、作業はもっと簡単です。次のように実行するだけで、選択したビルドディレクトリの中にHTMLをビルドできます:

$ make html

選択できるターゲットを見るためには、オプションを指定しないで make を実行してみてください。

PDFドキュメントを生成するには?

make latexpdfLaTeX ビルダー を実行します。その後ユーザ自身がすぐに実行できるようなpdfTexツールチェインを呼び出しす。

オブジェクトのドキュメントを書く

Sphinxの主な目的の一つが、簡単に ドメイン に属する オブジェクト (非常に一般的な意味です)のドキュメントを書けるようにする、というものです。ドメインというのはお互いに関連する、オブジェクトの型を集めた物です。オブジェクトの説明を作成したり、参照したりできます。

もっとも使用されるドメインは、Pythonドメインです。Pythonの組み込み関数の enumerate() のドキュメントを書く場合には、作成しているソースに次のように書き加えます:

.. py:function:: enumerate(sequence[, start=0])

   Return an iterator that yields tuples of an index and an item of the
   *sequence*. (And so on.)

これは次のようにレンダリングされます:

enumerate(sequence[, start=0])

sequence の要素と、そのインデックスのタプルを生成するイテレータを返します(....など)

ディレクティブの引数は、説明したいオブジェクトの signature です。コンテンツには、それに対するドキュメントそのものを書きます。複数のシグネチャを、1行ごとに書くこともできます。

Pythonドメインはデフォルトのドメインとなるので、それに関する設定を変更していない限りは、次のようにドメインを指定するプリフィックスを付けずに書いても、同じ結果となります:

.. function:: enumerate(sequence[, start=0])

   ...

もしデフォルトのドメインに対してデフォルトの設定を使い続けたい場合は、同じ事をしてください。

これ以外にも、 py:class, py:method など、Pythonの他のオブジェクトの種類のドキュメントを書くためのディレクティブがいくつも定義されています。また、これらのオブジェクトの型ごとに、相互参照を行うための role も定義されています。このマークアップを記述すると、 enumerate() のドキュメントへのリンクが作成されます:

The :py:func:`enumerate` function can be used for ...

実際に試してみたのがこれです: enumerate()

繰り返しになりますが、Pythonのドメインがデフォルトで設定されている場合には py: という接頭辞を外して書くこともできます。また、その enumerate() の実際のドキュメントが、どのファイルに書かれているのか、ということを気にする必要はありません。Sphinxが自動で見つけてリンクを張ってくれます。

ドメインごとに、シグニチャをどのように見せることができるのか、というルールは変わってくるでしょう。フォーマットをどのようにきれいに整えたり、C/C++ドメインのように引数の型にリンクを張るなどの言語ごとの特別な機能が追加されることもあります。

more info 使用できるすべてのドメインと、それらのディレクティブ/ロールについて知りたい場合には、 Sphinxドメイン を参照してください。

基本設定

最初の方で、Sphinxがドキュメントをどのように処理するのかを制御する、 conf.py というファイルがあるということについては軽く紹介しました。このファイルはPythonのソースファイルとして実行され、中に設定値を記述できます。上級のユーザは、Sphinxが処理をする際に、 sys.path を拡張したり、ドキュメントの記述するバージョン番号を取得してくるために、製品コードをインポートして情報を得るような、いくつかの処理を実装するでしょう。

おそらく多くのユーザが変更したがると思われるような設定値については、 sphinx-quickstart を通じて、 conf.py に既に書き込まれ、最初はコメントアウトされた状態になっています(Pythonの標準的な文法で、 # を書くと行の残りの内容がコメントになる)。デフォルト値を変更する場合には、 # 記号を削除して、値を変更してください。 sphinx-quickstart が自動的に追加しない設定値については、設定行を追加してください。

Pythonの文字列、数値、リストなどの文法を利用して設定ファイルを書く必要があります。設定ファイルは、最初の行のエンコーディング宣言の通り、デフォルトではUTF-8形式で保存されます。文字列の値として、非アスキー文字をしようしたい場合には、Pythonのユニコード文字列(例: project = u'日本語版Expose')を使用する必要があります。

more info すべての使用可能な設定値については、 ビルド設定ファイル(conf.py) のドキュメントを参照してください。

Autodoc

もしもPythonで書かれたコードのドキュメントを書こうとしている場合には、docstring形式でソースファイル中に既に多くのドキュメントを書いているでしょう。Sphinxは “autodoc” という 拡張機能 を利用することでソースファイルからdocstringを抽出してくて文章に取り込むというのをサポートしています。拡張機能はPythonで書かれたモジュールで、Sphinxのプロジェクトに様々な機能を付加します。

autodocを使用するためには、 conf.pyextensions という設定値に 'sphinx.ext.autodoc' という文字列を追加して、この機能を有効化する必要があります。追加すると、いくつかのディレクティブがプロジェクトに追加されます。

例えば、 io.open() という関数に関するドキュメントであれば、次のように記述すると、シグネチャやdocstring情報はソースファイルから読み取ります:

.. autofunction:: io.open

autodoc関連のディレクティブのmembersオプションを利用すると、クラスやモジュールの要素のドキュメントを自動的に作成することもできます:

.. automodule:: io
   :members:

autodocはモジュールをインポートしてdocstringの情報を収集する必要があります。そのため、ドキュメント対象のモジュールを読み込むために、 conf.py の中で、適切なパスを sys.path に追加する必要があります。

警告

autodoc はドキュメンテーションされるモジュールを インポート します. もしインポートによる副作用があれば、 sphinx-build が実行されるとき autodoc により実行されます。

もしあなたが (ライブラリモジュールではなく) スクリプトをドキュメント化したいのであれば、スクリプトのメインルーチンが if __name__ == '__main__' 条件により保護されていることを確認して下さい。

more info autodoc機能の完全な説明は、 sphinx.ext.autodoc の説明を参照してください。

Intersphinx

Python documentation をはじめとして、Sphinxで作られたドキュメントが多数インターネット上で公開されています。あなたのドキュメントからそれらのドキュメントへのリンクを作成したい時は sphinx.ext.intersphinx が利用できます。

intersphinxを使用するためには、 conf.pyextensions という設定値に 'sphinx.ext.intersphinx' という文字列を追加して、この機能を有効化した後、 intersphinx_mapping という設定値を設定する必要があります。

例えば、 Pythonライブラリマニュアルに含まれる io.open() へリンクするには、次のように intersphinx_mapping をセットアップする必要があります:

intersphinx_mapping = {'python': ('https://docs.python.org/3', None)}

これで :py:func:`io.open` のようなクロスリファレンスを記述可能になりました。現在のドキュメントの中に一致するターゲットが見つからないクロスリファレンスは、 intersphinx_mapping で指定したドキュメントからターゲットを探し、リンクされます (有効なターゲットのリストをダウンロードするため、設定で指定されたURLへアクセスします)。Intersphinxは :ref: を含む他の domains’ でも同様に動作します、しかしドメインロールでない :doc: では動作しません。

more info intersphinx機能の完全な説明は、 sphinx.ext.intersphinx の説明を参照してください。

さらに説明すべきトピック

脚注

[1]

これは基本的なレイアウトです。しかし、 conf.py設定ディレクトリ と呼ばれる他の場所に置くこともできます。詳しくは sphinx-quickstartの起動 をご覧下さい。