Python ドキュメント生成システム Sphinx

概要

Sphinx は Python の公式ドキュメント 等Python系プロジェクトで良く利用されるようになってきている Python で作成されたドキュメント生成システムです。

reStructuredText (reST) で記述することで目次やクロスリファレンスが付いた HTML、HTML Help、LaTeX、PDFを生成することが可能です。

文書の階層構造を容易に作成できたり、Pygments_ を利用することでソースコードの色付けも行なえます。

Python を利用して拡張することも比較的容易にできます。

Sphinx を利用しているプロジェクトを Projects using Sphinx にて見ることができますのでどのようなドキュメントが生成されるかの参考になります。

Sphinx は ドキュメント生成システムですのでAPIドキュメントのような物にも利用できますが、APIドキュメントに関しては Epydoc を利用した方が良いです。 Epydoc も reST を利用します。

インストール

easy_install でインストールするのが簡単です。

sudo easy_install -UZ Sphinx

依存関係も解決してインストールしてくれます。

とりあえず準備する

sphinx-quickstart コマンドを呼ぶことでディレクトリを用意してくれます。

sphinx-quickstart

いくつか質問してきます。とりあえず全部デフォルトで解答した物として以下を説明します。

Makefile を生成しておくとドキュメントの生成は簡単にできます。

make html

で HTML ファイルの生成が行なえます。 build/html 以下にHTMLファイルが生成されています。

Makefile を生成しない場合は sphinx-build コマンドを利用します。

sphinx-build コマンドでHTMLを生成する場合は以下のようにします。

sphinx-build -b html source build/html

ドキュメントを書く

ドキュメントの記述形式は reStructuredText(reST) になります。通常拡張子は .rst が多いです。 .txt を利用する方もいます。

ドキュメントは source ディレクトリの中に置きます。生成された source の中を見てみると ファイルとして conf.py と index.rst ができています。 index.rst の中身を見てみます。

だいたい以下みたいに生成されます。

Welcome to test's documentation!
================================

Contents:

.. toctree::
   :maxdepth: 2

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

Sphinx は 標準の reST には存在しない文法を カスタム directive として追加しています。

..toctree:: が文書の開始を表現しています。これは Sphinx 独自の物です。

source フォルダ直下 hoge.rst という文書を作成して追加する場合は :maxdepth:2 の下あたりに以下のように追加します。

.. toctree::
   :maxdepth: 2
   :numberd:

   hoge

拡張子を書く必要はありません。 :numberd: は章番号を自動で採番することをしめすフラグオプションです。 :numberd: の下に一つ改行が必要なことに注意してください。

上記の例のように明示的にファイル名を羅列していく事もできますが glob フラグを記述することで globbing を利用できます。

.. toctree::
   :maxdepth: 2
   :glob:

   intro*
   recipe/*
   *

この例だと intro* が intro で始まるファイル全部、 recipe/* が recipeディレクトリ以下に存在するファイル全部を意味します。 * が全部をしめしています。

glob を利用するとファイルの自然名前順に並ぶことになります。

最初に用意されている genindex 、 modindex 、 search は general index、module index、search pageの生成です。不要であれば消してしまっても問題ありません。

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

また _ で始まるファイルやディレクトリは特殊用途に利用しますので自分で作成するドキュメントには利用しない方が良いでしょう。

PDFの直接生成

直接 PDF を出力することができます。

Sphinx から直接 PDF を生成するには rst2pdf が必要です。 rst2pdf のインストールや設定に関しては rst2pdf で reStructuredText から PDF を生成する を参照してください。

動作が確認できたら Sphinx の設定をします。設定手順は rst2pdf のマニュアル に詳細に記述がありますのでそのままです。

Sphinx の conf.py の extensions に 'rst2pdf.pdfbuilder' を追加し、 PDF の設定をします。

extensions = ['sphinx.ext.autodoc','rst2pdf.pdfbuilder']
pdf_documents = [
       ('index', u'MyProject', u'My Project', u'Author Name'),
   ]
pdf_stylesheets = ['sphinx','kerning','a4','ja']

Makefile に以下を追加します。

pdf:
       $(SPHINXBUILD) -b pdf $(ALLSPHINXOPTS) ${BUILDDIR}/pdf
       @echo
       @echo "Build finished. The PDF files are in ${BUILDDIR}/pdf."

rst2pdf で reStructuredText から PDF を生成する に従ってちゃんと設定されていれば、問題なく生成されるはずです。

もし rst2pdf を直接コマンドラインから起動するとエラーが発生しないのに Sphinx でエラーが発生する場合、 sphinx-build スクリプトの先頭に書かれているパスが異常な可能性があります。

which python
# 確認した Python のパスをメモ
vi $(which sphinx-build)
# sphinx-build の shebang(#!の部分)を書き変え

これで動作するはずです。

他のフォーマットから Sphinx への移行

Sphinx では reStructuredText を利用します。よって reStructuredText に変換する必要があります。

変換スクリプトがいくつか開発されています。

Sphinx マニュアル

和訳されたマニュアルがあります。

• Sphinx マニュアル和訳(渋川氏版)
• Sphinx マニュアル和訳(増田氏版)

変更履歴

• 2009/12/16:rst2pdfの記述を追加
• 2009/07/29:公開