Sphinx：検索結果が文字化ける場合の対策

仕事でSphinx使っていて、趣味でSphinxのテーマを作ってます。

Sphinx1.1からは、日本語もちゃんと検索出来るようになったので、
隠していた検索ボックスを表示するようにしました。

Sphinxの検索機能では、

conf.pyでhtml_copy_source = Trueを指定していると、
検索時に検索結果を表示してくれます。

この結果表示は、ソースファイルのコピーを参照して、
そのままhtmlに表示しているので、
ソースとhtmlの文字コードを変えていると、文字化けが発生します。

その対策方法を書きます。

Solarized化してみました

Solarized Sphinx ThemeというSphinxのテーマを見て感化されました。

長く見るのに適した配色のほうがいいよな、ってことで職場のSphinxのテーマの配色も、このブログの配色も、みんなSolarizedっぽくしてみました。

・・・JINS PCと一緒で、そのうち飽きる気がしないでもないです。

アイコン解決

アイコン自作するの面倒になったので、再配布可能なアイコンを探して、利用することにしました。

再配布可能なアイコンは、たいていクレジットの表記が必須なのですが、具体的にどう表記すれば良いかを明記している人はほとんどいないような？たぶんホームページへのリンクを付ければよいのでしょうが、正直使いづらい。

そんな中で、ちゃんとクレジットの表記例を載せていて、かつ、アイコンもいっぱいあるのを発見。


Footerにリンク入れれば再配布OK。お金を払ってクレジット表記を消す方法も明記されているので、いろいろ便利。とりあえずこれを使用させていただくことに決定。



後は、CSSを直せば公開できますね！

今は sphinxjp.themes.bizstyle を適当にカスタマイズしたのを使っているのですが、もうちょっと変えたいんですよね。

bizstyle は、スタイルを工夫してどんな色でもだいたい大丈夫にしていて凄いと思います。
でも、個人的には中間色を使って、もう少し表現力を上げたい。
 
そこで、中間色を生成するJinja2のフィルタを作ってSphinxで使いたいのですが・・・。
軽くググった感じでは、Sphinxで使っているJinja2のEnviromentへのアクセス方法がイマイチわからない・・・。orz。

カスタムフィルタを追加すると、Jinja2の表現力ってかなり上がるとおもうんですけれど、
Sphinxでチャレンジしている人はあんまりいないみたいですね。

仕方が無いので軽くソースを追ってみました。
フィルタの追加は、そんなに難しくなさそうなので、今度チャレンジしてみます！

近況の記録：アイコンめー！

MTG-Guildの開発をサボって、Sphinxのテーマいじりをしています。
仕事の効率化になる上に、趣味も兼ねているので、こっちのほうが自然と進みます。

職場の環境がIEメインなのですが、各所でdisられているIEも、Sphinxを使う分にはかなり良いですね。IEだとセキュリティ的に悪名高いVBSが使えます。この悪魔の言語を使うことで、htmlからファイルを直接いじったりbatファイルを起動できたりします。つまり、Sphinxをwikiっぽく使えます。

これは便利なのでぜひ広めよう、と思い
外部に公開する準備をしてきました。

Sphinxのファイルの拡張子とか

うーん。Sphinxのファイルの拡張子って、.rstと.txtのどっちが良いんだろう？
Sphinxを仕事で使うようになって、いろいろモヤモヤとしてきたので、整理してみます。

Sphinxで日本語を使う時の注意点のメモ（Windows限定）

自作テーマを社内展開用に整理していたら、文字コードの迷宮に迷い込んでしまいました。
あまり一般的な事例ではないかもしれませんが、どこかの誰かと未来の自分の為に、対策をメモしておきます。

Sphinxでhtmlhelpを出力するときの注意点

仕事でSphinxを使いはじめています。
Windowsヘルプ（いわゆるchmファイル）をSphinxから作るときに、文字コード関連でちょっと苦戦しました。

普通にやっているつもりが、文字化けしちゃうんですよね・・・。


結論を書いちゃうと、これでOKみたいです。

1. conf.pyで、
   language = 'ja'
   という記述を入れておく
2.  sphinx\themes\layout.htmlを修正する。
   83行目：
       <meta http-equiv="Content-Type" content="text/html; charset={{ encoding }}" />
   を、
       {%- if encoding == 'cp932' %}
       <meta http-equiv="Content-Type" content="text/html; charset=shift-jis" />
       {%- else %}
       <meta http-equiv="Content-Type" content="text/html; charset={{ encoding }}" />
       {%- endif %}
   に変える。
3. 日本語パッチのあたったSphinxを使う

Mercurialって日本語大丈夫になったのですね！

Sphinxで書いたドキュメントをバージョン管理していなかった理由は、使いたいと思ったツール（Mercurial）が、日本語のファイル・フォルダ名をうまく扱えなかったことが一番の理由でした。

（バザールは、日本語使えるようですが、シェルエクステンションがいまいちっていう評判を聞くので、おっさん的にきついので・・・）

 ですが、現在の最新バージョンは、日本語でも大丈夫みたいですね。
試しに入れてみた（tortoisehg-2.2.1-hg-2.0.1-x86.msi）のですが、以前はうまく認識できなかったファイルやフォルダも、ちゃんと認識されてますね。

よーし。これなら本格的に使えるぞ！
日本語のパスはダメとか、Windows上で仕事を進めてるとありえなかったんですよ。

本格的にチュートリアル（JapaneseTutorial）とかやってみることにします！

Mercurialを知らない人はこちら→Wikipedia

追記：

あれ？ これって、win32mbcsのエクステンションがデフォルトで動くようになっているだけなんじゃ・・・

Sphinxの同期

Sphinx、良いですね。


前にもちょっと書きましたが、テンプレートを自分用に修正して、
htmlからソースのrstファイルをテキストエディタで開くボタンと
htmlを再生成するバッチを起動するボタンを追加してみました。

おかげで、個人用wikiみたいに使えていて良い感じです。

 同じ職場のチーム内で共有したほうが良い資料は、
共有フォルダで公開してます。

rstの同期は、
分散バージョン管理とかでやるのが良いのでしょうが、
mercurialを 勉強するのが 面倒でやれてません。

なので、昔ながらのbatファイル＆タスクスケジューラで同期をとっているのですが、
先日、ネットワークにつながっていない状態で不具合を起こしてしまい、
ローカルのrstファイルが削除されてしまいました。

１．共有フォルダにカレントを移す
２．ファイルを全部削除
３．XCOPY

ネットワークにつながっていなかったので、１が失敗し、
ローカルのファイルを削除してしまったわけです。

まぁ、元々の書き方に問題があったわけだし、
分散バージョン管理しろ、ってことなのでしょうが、
今更仕組みを再構築するのもだるいので、
robocopyを使って同期取ることにしました。
これだとファイルの削除も一緒にやってくれるので、安全です。

XPは、robocopyが無かったので、以下のサイトからリソースキットを落としてインストールしました。

WindowsServer2003の英語版リソースキット（XPの日本語でも動くらいしい）


追記：

本件、一生懸命作っていたファイルが削除されてしまった怒りから書いてみたのですが、
どうみても、自分が悪いだけですね。

Sphinx良いですね

自分の仕事用の手順書をまとめるのに使用してみました。
構造化した感じのwikiをローカルで構築できるので、重宝しそう。

難があるとすると、
１．日本語の扱いが微妙
２．ビルドするのが面倒
３．ビルドしたｈｔｍｌからソースを編集できない

１．はパッチがあるので、それを適用すると何となく動きます。
２と３は、気合でhtmlをいじって、なんとかワンクリックでできるようにしてみた。

・・・結構、快適ですねぇ。
だらだら書いてもそれっぽくなるので、文章の内容に集中できるし、
あとから編集するのも楽。
これは広めていこう。