(6日目) Sphinx 拡張の紹介
Sphinx には Sphinx 拡張(Sphinx extension)と呼ばれるプラグイン機能があります。
Sphinx 拡張を使うとドキュメントを書くのがより便利になったり、
ドキュメントの表現がより豊富になったりします。
今日はその Sphinx 拡張の中から僕がよく使うもの、便利そうで使ってみたいものを
それぞれいくつかピックアップしてご紹介します。
sphinx.ext.todo
Sphinx に同梱されている拡張モジュールで、ドキュメントに ToDo を書き残すことができます。
有効にするには conf.py に以下の記述を追加します。
# sphinx.ext.todo モジュールを読み込む extensions += ['sphinx.ext.todo'] # ToDo 項目を表示する (デフォルトは表示しない; False) todo_include_todos = True
sphinx.ext.todo モジュールを読み込むと rst ファイルの中で todo ディレクティブが使えるようになります。
.. todo:: あとで書く
このモジュールを使うと、積み残しのドキュメントタスクを直接埋め込むことができます。
また、todolist ディレクティブを使うとドキュメント内のすべての ToDo をリストにして表示します。
.. todolist::
なお、これらの ToDo は conf.py の todo_include_todos が True のときだけ表示されるため、
他の人に成果物を渡したり、一時的に見せるときに False にすると ToDo を表示しないものを出力することができます。
sphinx.ext.pngmath / sphinx.ext.jsmath
Sphinx に同梱されている拡張モジュールで、LaTeX 形式の数式をサポートします。
sphinx.ext.pngmath は dvipng を介して、sphinx.ext.jsmath は jsMath (JavaScript) を介して数式を表示します。
どちらも依存パッケージを追加でインストールする必要がありますが、
数式を多く含むドキュメントを書く場合は必須の拡張モジュールです。
ここではインストールがかんたんな sphinx.ext.jsmath を使用します。
Sphinx には jsMath で利用するファイル群が含まれていないので、別途インストールします。*1
$ wget 'http://downloads.sourceforge.net/project/jsmath/jsMath/3.6e/jsMath-3.6e.zip' $ unzip -d _static jsMath-3.6e.zip $ wget 'http://downloads.sourceforge.net/project/jsmath/jsMath%20Image%20Fonts/1.3/jsMath-fonts-1.3.zip' $ unzip jsMath-fonts-1.3.zip $ mv jsMath/fonts _static/jsMath-3.6e $ rmdir jsMath
次に conf.py で sphinx.ext.jsmath モジュールを有効にします。
# sphinx.ext.jsmath モジュールを読み込む extensions += ['sphinx.ext.jsmath'] # jsMath のパスを設定する (_static/ からの相対パス) jsmath_path = 'jsMath-3.6e/easy/load.js'
sphinx.ext.jsmath モジュールを有効にすると math ディレクティブが利用できるようになります。
math ディレクティブに数式を渡すときれいな数式として表示してくれます。
.. math:: (a + b)^2 = a^2 + 2ab + b^2
.. math::
:label: quite
(a + b)^2 &= (a + b)(a + b) \\
&= a^2 + 2ab + b^2
.. math:: e^{i\pi} + 1 = 0
:label: euler
label オプションを付けると数式にラベルと数式番号を付けることができ、
また :eq: ロールを用いて参照することができます(例: :eq:`euler` )。
sphinxcontrib.blockdiag / sphinxcontrib.seqdiag など
いくつか前の記事 で紹介しましたが、blockdiag シリーズの図を埋め込みます。
多くのドキュメントで役に立つ拡張モジュールだと思います。
既に紹介しているのでここでは説明を割愛します。
sphinxcontrib.plantuml
ドキュメントに各種 UML 図を埋め込むための Sphinx 拡張です。
UML 図の生成に PlantUML を利用しています。
利用する際は easy_install でインストールします。
$ sudo easy_install sphinxcontrib-plantuml
また、sphinxcontrib.plantuml は内部で PlantUML を呼び出すため、別途 PlantUML のインストールが必要です。
PlantUML は Java で動作するアプリケーションなので、実行には JRE が必要になります。
PlantUML 自身は Java パッケージとして配布されているので、plantuml.jar をダウンロードするだけです。
$ sudo apt-get install openjdk-6-jre $ wget 'http://downloads.sourceforge.net/project/plantuml/plantuml.jar'
続いて、conf.py に設定を記述します。
# sphinxcontrib.plantuml モジュールを読み込む extensions += ['sphinxcontrib.plantuml'] # PlantUML の起動方法を設定する plantuml = ['java', '-jar', '/path/to/plantuml.jar']
sphinxcontrib.plantuml モジュールを有効にすると uml ディレクティブが利用できるようになります。
uml ディレクティブに定義を渡すと UML 図として表示してくれます。
.. uml::
Alice -> Bob: Hi!
Alice <- Bob: How are you?
.. uml::
class "This is my class" as class1 {
+myMethods()
-myMethods2()
String name
}
class class2 as "It works this way too" <<Serializable>> {
String name
}
class2 *-- "foo/dummy" : use
PlantUML はシーケンス、ユースケース、クラス、アクティビティ、コンポーネント、ステート、オブジェクトの各種 UML 図をサポートしているので、
ソフトウェア開発で UML を多用しているケースでは大変役に立つと思います。*2
なお、図ごとに Java のプロセスを立ち上げるので大量に図が入っている場合は少しビルドに時間がかかるようです。
sphinxcontrib.googlechart
拙作の Google Chart を利用してグラフを生成する拡張モジュールです。
以下のグラフに対応しています。
- 円グラフ (2D/3D)
- 折れ線グラフ
- 棒グラフ
- ベン図
- 散布図
利用する際は easy_install でインストールします。
$ sudo easy_install sphinxcontrib-googlechart
それぞれのグラフのサンプルはマニュアルページで見ることができます。
sphinxcontrib.googleanalytics
Sphinx で生成した HTML ページに Google Analytics のビーコンを埋め込むための Sphinx 拡張です。
テンプレートの変更などの面倒がないため、Google Analytics ユーザーは必須の拡張モジュールです。
利用する際は easy_install でインストールします。
$ sudo easy_install sphinxcontrib-googleanalytics
インストールしたあとは conf.py に設定を記述します。
# sphinxcontrib.googleanalytics モジュールを読み込む extensions += ['sphinxcontrib.googleanalytics'] # GoogleAnalytics の ID googleanalytics_id = 'UA-xxxxxxxx-1'
あとは make html で HTML を生成するだけで完了です。
sphinxcontrib.youtube
Sphinx ドキュメントに Youtube ムービーを埋め込むための Sphinx 拡張です。
現在、sphinxcontrib.youtube はソースのみが公開されている状況なので、
bitbucket から直接ソースコードをダウンロードして利用します。
以下の例では、構成ファイルが 2つだけなので、wget で直接ダウンロードしています。
$ mkdir -p lib/sphinxcontrib $ wget -O lib/sphinxcontrib/__init__.py https://bitbucket.org/birkenfeld/sphinx-contrib/raw/14db1e6b4f01/youtube/sphinxcontrib/__init__.py $ wget -O lib/sphinxcontrib/youtube.py https://bitbucket.org/birkenfeld/sphinx-contrib/raw/14db1e6b4f01/youtube/sphinxcontrib/youtube.py
ダウンロード後、conf.py に設定を記述します。
# sphinxcontrib.youtube 用にライブラリパスを追加 sys.path += ["lib"] # sphinxcontrib.youtube モジュールを読み込む extensions += ['sphinxcontrib.youtube']
使い方は youtube ディレクティブに動画 ID を指定するだけです。
.. youtube:: IN9YE_HjQQk
sphinxjp.themes.bizstyle
@shkumagai 作の Sphinx のテーマを切り替える sphinxjp.themes.* の一つです。
耳にする範囲ではかなり評判のいいテーマです。
利用する際は easy_install でインストールします。このモジュールは区切りが . なので間違えないよう注意します。
$ sudo easy_install sphinxjp.themes.bizstyle
インストールしたあとは conf.py に設定を記述します。
# sphinxjp.themecore モジュールを読み込む (sphinxjp.themes.bizstyle ではないのに注意) extensions += ['sphinxjp.themecore'] # テーマ設定 html_theme = 'bizstyle'
あとは make html するだけで、こんな格好いいドキュメントになりますね :-)
その他のモジュール
この記事を作るにあたっておもしろそうなモジュールをピックアップしていたところ、
こんなモジュールも見つかりました。
どれも使いかたによっては、便利な場面がありそうな気がします。
- docxbuilder
- @shimizukawa 作の .docx ビルダー。make docx で Word 文書として出力されます。
- まだバージョンが 0.0.1alpha と低いですが、これからが非常に楽しみです。
- sphinxfeed
- cheeseshop
- issuetracker
- github, bitbucket などのイシュートラッカーへのリンクを簡単に作れるモジュールだそうです。
- いい使い方はあまり思いつかなかったのですが、動作に興味があります。
- sadisplay
- SQLAlchemy のモデルを可視化するモジュールです。
- 内部で PlantUML or graphviz を利用しているとのこと。
- ER 図が簡単に書けるのかもしれません。誰か試してみて！
- sphinxjp-shibukawa
- 拙作。簡単なスケジュール表が作れるモジュールです。
- 名前の通り @shibukawa さんへのプレゼントとして作られたモジュールです。
その他にも便利そうなモジュールがたくさん存在します。
PyPI や Google で検索するなどして、便利なモジュールを検索してみてください。
