Sphinxは、HTML文書・LaTeXを用いたPDFファイル・EPUB形式の電子書籍などを同一のソースファイルから作成できるドキュメント作成プログラムです。通常のプログラムのコンパイルのように、makeコマンドを使ってそれぞれの形式の文書を作成します。

Sphinxのソースファイルは、reStructuredText(拡張子は .rst)と呼ばれるマークアップ言語で記述します。以下に、サンプルをお見せしますが、これらはすべて特別なレイアウト調整を行っておらず、デフォルトのレイアウトを使っています。このように、非常に完成度の高い多様な文書が同一のソースから作成できるというのは魅力的ですね。

以下、Ubuntu 11.10(oneiric)でSphinxを使ってみたという備忘録です。
詳細は、Sphinxの日本語マニュアルを参照してください。

Sphinxの使用例


sphinx-latex
make latex→make all-pdf-jaで生成したPDF文書。contentsのリンクは自動的に生成されています。このように、インデックスが自動生成されるところもSphinxの利点です。改ページ位置の調整はできるのでしょうか?なお、デフォルトのconf.pyでは、ドキュメントの種類が「manual」になっていますが、この場合は「howto」を指定しました。
latex_documents = [
('index', 'test.tex', u'量子力学入門',
u'Masahiko Yamaguchi', 'howto'),
]


sphinx-html
make htmlで生成したHTMLをFirefoxで開いているところ。このまま公開できそうな完成度です。cssファイルは、build/html/_staticフォルダの中に、またTeXの数式画像はbuild/html/_images/mathフォルダの中に入っています。

sphinx-epub
生成したEPUBをSigilで開いています。数式以外の文字はSigilで再編集することもできます。FBReaderでは、文中のTeXフォントがすべて別行立てになってしまいます。また。スマートフォンではCopperReaderを使って読むことができました。ただし、数式はpng画像のため、かなり粗い表示になってしまいます。jsMathを使えばもう少しましかも。


Sphinxを使用する際の注意点

数式の入っていない普通の文書でHTML文書やEPUBを作るだけなら問題ありませんが、LaTeXを利用する場合、platexとdvipdfmxがUTF-8に対応していなければ失敗します。ちなみに、UbuntuとFedoraのTeXLiveはUTF-8に対応していませんが、TeXLive2011を入れれば使えます。メジャーなディストリですと、Vine LinuxぐらいしかUTF-8に対応していないのでは?

[2012.01.13 追記]
Makefileにnkfコマンドを加えることで、Ubuntu 11.10のデフォルトのTeXLiveでも利用可能であることがわかりました。詳しくは次回の記事でまとめます。

Sphinxのインストール

Ubuntu 11.10では、デフォルトのリポジトリに含まれていますので、ソフトウェアセンターで「python-sphinx」を検索して入れるか、次のコマンドでインストールします。

$ sudo apt-get install python-sphinx

Sphinxドキュメントのひな形を生成する

Sphinxのドキュメントを生成するためには、Makefileとpythonで書かれたconf.pyという設定ファイルおよびサンプルのrstファイルなどが必要ですが、次のコマンドを実行していくつかの質問に回答していくことで、コンパイルに必要な一式のファイル群が生成されます。

$ sphinx-quickstart

コマンドを実行すると、次のような表示が出ます。(すべての出力を掲載しました)
$ sphinx-quickstart
Welcome to the Sphinx 1.0.7 quickstart utility.

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

Enter the root path for documentation.
> Root path for the documentation [.]: test

You have two options for placing the build directory for Sphinx output.
Either, you use a directory "_build" within the root path, or you separate
"source" and "build" directories within the root path.
> Separate source and build directories (y/N) [n]: y

Inside the root directory, two more directories will be created; "_templates"
for custom HTML templates and "_static" for custom stylesheets and other static
files. You can enter another prefix (such as ".") to replace the underscore.
> Name prefix for templates and static dir [_]:

The project name will occur in several places in the built documentation.
> Project name: test
> Author name(s): vineuser

Sphinx has the notion of a "version" and a "release" for the
software. Each version can have multiple releases. For example, for
Python the version is something like 2.5 or 3.0, while the release is
something like 2.5.1 or 3.0a1. If you don't need this dual structure,
just set both to the same value.
> Project version: 1.0
> Project release [1.0]:

The file name suffix for source files. Commonly, this is either ".txt"
or ".rst". Only files with this suffix are considered documents.
> Source file suffix [.rst]:

One document is special in that it is considered the top node of the
"contents tree", that is, it is the root of the hierarchical structure
of the documents. Normally, this is "index", but if your "index"
document is a custom template, you can also set this to another filename.
> Name of your master document (without suffix) [index]:

Sphinx can also add configuration for epub output:
> Do you want to use the epub builder (y/N) [n]: y

Please indicate if you want to use one of the following Sphinx extensions:
> autodoc: automatically insert docstrings from modules (y/N) [n]:
> doctest: automatically test code snippets in doctest blocks (y/N) [n]:
> intersphinx: link between Sphinx documentation of different projects (y/N) [n]:
> todo: write "todo" entries that can be shown or hidden on build (y/N) [n]:
> coverage: checks for documentation coverage (y/N) [n]:
> pngmath: include math, rendered as PNG images (y/N) [n]: y
> jsmath: include math, rendered in the browser by JSMath (y/N) [n]:
> ifconfig: conditional inclusion of content based on config values (y/N) [n]:
> viewcode: include links to the source code of documented Python objects (y/N) [n]:

A Makefile and a Windows command file can be generated for you so that you
only have to run e.g. `make html' instead of invoking sphinx-build
directly.
> Create Makefile? (Y/n) [y]:
> Create Windows command file? (Y/n) [y]: n

Finished: An initial directory structure has been created.

You should now populate your master file test/source/index.rst and create other documentation
source files. Use the Makefile to build the docs, like so:
make builder
where "builder" is one of the supported builders, e.g. html, latex or linkcheck.
項目数が多いですが、気にしなければならないのは下記の赤字の部分ぐらいで、それ以外はすべてデフォルトのまま(Enterキー押下で次へ)で問題ないでしょう。

[ルート・パスの設定]
> Root path for the documentation [.]: docs
カレントディレクトリ内の「ドキュメントのソースファイルと生成ファイル一式を保存するディレクトリ」を指定しますこの場合は「docs」というディレクトリにソースファイルのひな形が保存されます。[推奨]

[ソースファイルと生成ファイルの分離]
> Separate source and build directories (y/N) [n]: y
buildディレクトリ(生成ファイル群を保存)とsourceディレクトリ(ソースファイル一式を保存)に分離して保存するには、ここで「y」を指定します。[推奨]

[プロジェクト名と著者名の設定]
> Project name: 量子力学入門
> Author name(s): Masahiko Yamaguchi

プロジェクト名(ドキュメント全体のタイトルとなります)と著者名を指定します。[必須]

[バージョンの設定]
> Project version: 1.0
文書のバージョンを数値で指定します。[必須]

[EPUBの設定]
> Do you want to use the epub builder (y/N) [n]:
EPUBを作成する場合は「y」を指定します。[デフォルトでは無効]

[extensionの設定]
> pngmath: include math, rendered as PNG images (y/N) [n]: y
LaTeXの数式フォントを表示させるには、ここで「y」を指定します。JSMathとは共用できません。[デフォルトでは無効]

[Makefileの設定]
> Create Windows command file? (Y/n) [y]: n
デフォルトではWindows用のmake.batを生成します。Linuxでは必要ないので「n」を指定します。

これらの設定は、後から設定ファイル(conf.py)で修正することも可能です。

LaTeXでPDFを作成する

まず、sphinx-quickstartコマンドで指定したドキュメント・ルートで下記のコマンドを実行します。

$ make latex

これで、build/latexというフォルダ内にtexのソースファイルと独自のstyファイルが保存されます。続いて、このフォルダに移動してmakeします。

$ cd build/latex
$ make all-pdf-ja


[注意]
Ubuntu 11.10のデフォルトのTeXLiveではUTF-8に対応していないので使えません。TeXLive2011を手動でインストールする必要があります。また、TeXLive2011でも設定ファイルを書き換えないとコンパイル時にエラーが出て失敗します。次回に記事にしたいと思いますが、早く試してみたいという方はこちらのパッチを参考にして、source/conf.py、build/latex/Makefile、およびbuild/latex/sphinx.styを変更して、試してみてください。

[2012.01.13 追記]
Makefileにnkfコマンドを加えることで、Ubuntu 11.10のデフォルトのTeXLiveでも利用可能であることがわかりました。デフォルトのTeXLiveを利用する場合も、このパッチに該当する変更を行わなければなりませんが、 -kanji=utf8 の部分は削除する必要があります。詳しくは次回の記事でまとめます。

HTMLを作成する

sphinx-quickstartコマンドで指定したドキュメント・ルートで次のコマンドを実行するだけです。

$ make html

これで、build/htmlというフォルダの中にindex.htmlなどのデータ一式が生成されます。LaTeXでドキュメント生成が成功していれば、数式はTeXのフォントの画像が使われます。

EPUBを作成する

sphinx-quickstartコマンドで指定したドキュメント・ルートで次のコマンドを実行するだけです。

$ make epub

これで、build/epubというフォルダの中にEpub.epubが生成されます。数式は荒い画像になってしまうため、スマートフォンでは表示が汚くなってしまうかも知れませんが、普通の文書なら問題ありません。

LaTeXドキュメントのサンプル

LaTeXで変換する際に使用した文書の一部を掲載しておきます。

.. toctree::の下の部分に各章の文書名(拡張子を除いたrstファイルの名称)をリストアップすると、自動的にコンテンツリストにリンクが貼られます。以下は、index.rst(トップページ)と同じ階層にsec1.rst(1章目の文書)を置いている場合の例です。index.rstと同階層にフォルダを置き、その中に各章の文書を置く場合は、 :maxdepth: を「3」にして「フォルダ名/ファイル名」の形で指定する必要があります。

[index.rst]
.. 量子力学入門 documentation master file, created by
   sphinx-quickstart on Wed Jan 11 14:50:45 2012.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

量子力学入門
==================================

Contents:

.. toctree::
   :maxdepth: 2

   sec1

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

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

[sec1.rst]
==============
演習問題
==============

演習1 問題
==============

 ハミルトニアンが

.. math:: H=-\dfrac{\hbar ^{2}}{\,2m\,} \dfrac{d^2}{dx^2}+V(x)
  :label: eq1
与えられる1次元運動で、ポテンシャルが :math:`x` の偶関数 :math:`V(x)=V(-x)` である場合には、束縛状態の固有関数は :math:`x` の偶関数か奇関数のどちらかであることを証明せよ。ただし、1次元の束縛状態のエネルギー関数はとびとびで、どれにも縮退はないことが知られている。

今時の文書作成は、makeしてコンパイルするんですね〜。プログラミングが好きな人なら、何かまとまった書籍を作りたくなるのではないでしょうか?

ちなみに、今週末はセンター試験ですね。
受験生の皆さん、悔いの残らないように頑張ってください!(いや、受験生は見てないだろjk