読者です 読者をやめる 読者になる 読者になる

本格的な数式を含むWebページを作る方法を探してからSphinxを選ぶまで

SphinxPython製の

美しいドキュメントを簡単に生成することができるドキュメンテーションツール

引用元:http://sphinx-users.jp/

です.

美しいドキュメントを生成するツールとしてはLaTeXがありますが,LaTeXの基本機能ではPDF(とDVI)の出力しかできません.Sphinxで書かれたWebページの例としては上で紹介した引用元のhttp://sphinx-users.jp/を挙げておきます.


一方,Sphinx

など,いろいろな形式で出力ができます.Word出力もできるそうです.

Sphinxを導入した理由

今まで自分がまとめたTipsを公開することが目的でした.内容に数式が沢山あったので,数式対応のシステムを探しました.

以下の3つの要件が外せないものとして頭の中にありました.

  1. ストレスなく文章を作ることが出来る.
  2. ブラウザでの表示が速い.
  3. 外部サービスに依存しない.

いろいろ調べた結果

を比較見当することになりました.

MathJax

www.mathjax.org

最初に見つけたものがMathJaxです.Webページに数式を載せる方法として標準に近いものだそうです.はてなブログでも標準サポートされています.
{ \displaystyle
\left(-\frac{\hbar^2\nabla^2}{2m}+V\left(x\right) \right)\psi\left(x\right)=E\psi\left(x\right) 
}
この数式は

[tex:{ \displaystyle
\left(-\frac{\hbar^2\nabla^2}{2m}+V\left(x\right) \right)\psi\left(x\right)=E\psi\left(x\right) 
}]

と書くだけで表示させることが出来ます.式が表示されている所で右クリックをすれば,LaTeXコードやMathMLでコピーすることができて非常に便利です.しかしLaTeXの数式機能をほぼ完全にサポートしていますが,LaTeXとは別のシステムで数式を作成するために自作のマクロを使うことが出来ません(簡単なマクロならMathJaxの設定で可能).パッケージの追加などは以ての外です.また,Webページを表示するたびにブラウザがレンダリングするため,クライアント側に負荷を与えてしまいます.長い数式(A4で5ページ程度)でテストしてみましたが,式番号を参照する機能まで有効化すると表示が完了するまで4,5秒程度の時間を要しました.これはノートパソコンでの結果ですが,iPhone(5s)で閲覧するとなんと10秒程もかかります.流石にこれでは遅すぎるため他の方法を探しました.LaTeXに比べて美しくないという不満もありました.

WordPress(とプラグイン

wordpress.org

WordPressプラグインを使う方法も考えました.LaTeX形式の数式を入れると自動的に画像に変換して埋め込んでくれるというものです.いくつかありましたが,基本的にそのプラグイン独自のWebサービスを利用するものでライセンスに縛られてしまいます.ライセンスは注意深く守れば良いものとしても,Webサービスが終了してしまってはどうしようもありません.WordPress公式サービスならまだ良いのですが,実用に耐えうると判断したプラグインは個人製作だったためWordPressの利用は断念しました.

なおここで紹介したプラグイン WP-Quick-LaTeX は非常に完成度の高い数式対応のプラグインです.LaTeX形式で埋め込んだ数式コードを自動的にsvg形式に変換してWebページに埋め込んでくれます.独自にWebサービスを利用していて本物のLaTeXを利用しているためTeXLiveに組み込まれている任意のパッケージを利用することができるというすさまじいものです.linkwareライセンスで,それに加えて非商用の制限が課せられています.

Google Chart API

developers.google.com

(きっと)終わらないWebサービスを探せば良い!!と考えを変えて見つけたのが,Google Chart APICharts  |  Google Developers)です.グラフを表示させるためのものらしいですが数式も表示できます.ただ,200文字までという文字数制限があり,利用を断念しました.複数行もサポートしていないのも痛かったです.

mimetex

mimetex.html

こちらは試す前に複数行の数式をサポートしていないという情報を見つけたために候補からは外れました.導入が面倒に感じたというのもあります.

LaTeX2HTML

www.latex2html.org

ではLaTeXからHTMLに変換すればよいではないか!!と考えてLaTeX2HTMLを試してみました.名前の通り,LaTeX形式をHTMLに変換するツールです.生成されるHTMLがあまりにも汚かったのでボツ.数式画像のスペーシングも好みに合いませんでした.自分でスクリプトを組んで調節すればよいのかとも考えましたが,それほどの技術が自分にないため断念.開発が2003年ころから止まっているのも不安でした.

そしてSphinxを見つける

絶望感に苛まれながらいろいろ調べていると,昔に見過ごしたSphinxを紹介するホームページを見つけました.(記憶はなかったのですがGoogle Search でリンクが青くなっていたので見たのでしょう)room6933.com
いやもうSphinxの素晴らしさはここで書き尽くされているので紹介するまでもないのですが,自分が特に熱いと感じたところを紹介します.

  1. 数式を自動的に軽いpng画像に変換して適切な大きさで埋め込んでくれる.簡単!!
  2. 数式生成には本物のLaTeXを利用するため,完全なLaTeXの機能がサポートされる.
  3. 本当に個人的な好みだが,Webで表示するときは数式はかすれ気味出会って欲しい.その方が読みやすい.
  4. HTMLで日本語を見やすくするために改行すると半角スペースが入ってしまうが,これを回避する拡張がある.
  5. 自分のPCの中で完結する.外部サービスに依存しない.
  6. 幾つかのテーマを選ぶことになるが,基本的な構成は同じなので色を変える程度の簡単な調節が容易.
  7. 静的なHTML生成されるため応答が非常に早い.
  8. 文章構造とディレクトリの構造を合わせて管理することが出来る.
  9. 生成できるドキュメントの種類が多いため,色々利用することが出来る.
  10. Sphinx関係のドキュメントがSphinxで書かれているため読みやすい.

これくらいでしょうか.当然のことながら1つ目(数式)への感動が極めて大きいです.もともとPythonのドキュメントを書くためのものだったらしく文章構造が明確に定まっている文書との相性が非常に良いです.LaTeXを普段使っていた人なら違和感なく利用できるでしょう.極めれば最初からLaTeXで書いたかのような文章をPDFで作ることもできそうです.プリアンブルをいじれるので自由度は大きいです.