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

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

＜基本設定＞

1. 日本語パッチのあたったSphinxを使う
2. スタンドアローン版をインストールしたディレクトリ配下のpython\libに、sitecustmoize.pyを追加する。ファイルの中身は、
   import sys
   sys.setdefaultencoding("mbcs")
3. conf.py で
   language = 'ja'
   としておく

sitecustmoize.pyを設定するのは嫌いなのですが、設定しないとソースファイルの親ディレクトリに日本語が含まれている場合にうまく動かないようです。ローカルで作っていたrstをネットワークフォルダ上に配置してmake htmlした時に、ネットワークフォルダに日本語のフォルダが含まれていて、はまりました。
language='ja'は、入れなくてもいいのですが、いれておくと色々良くなることが多いので、最初から設定しておくと良さげです。quickstartで作られるconf.pyは、微妙な感じがするので、特に自作テーマを作るときは、それに合わせて標準的なconf.pyを用意しておくとよさそうですね。

＜テーマをいじる場合の注意点＞

• jinja2のテンプレートはutf-8（BOM無し）で書く
• theme.confもutf-8 （BOM無し） で書く
• conf.pyでhtml_theme_optionsを指定する場合も、値をutf-8にエンコードする

※utf-8は、defaultのテーマを継承した場合です。
出力しているhtmlのエンコーディング指定に合わせる必要があります。
defaultのテーマの場合は、
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
　なので、utf-8です。 


ようは、変数の値がそのままテンプレートでレンダリングされるようです。だから、テンプレートに渡す時には、ちゃんと最終的な文字コードをあわせてエンコーディングしておきましょう。

デフォルト設定だと、そうそう起きない失敗だと思いますが、（社内展開を考えると、シフトJISのほうが喜ぶ人が多そうに思えたので）conf.pyにて「source_encoding = 'mbcs'」としたのが迷宮の入り口でした。ソースがmbcsだから、設定もmbcs?って思いましたが、最終形式に合わせるんですね。

（結局utf-8を喜ぶ人じゃないとSphinxは使わない気がする・・・。いろいろ面倒が多いので、この機会にUTF-8(BOM付）にそろえることにしました）

＜htmlテーマの変数をWindowsのbatファイルで使いたい場合＞

• .bat→.bat_tとする
• {{'\r'}}を行末にいれる
• .bat_t ファイルには、なるべく日本語を入れない。どうしても必要な場合はシフトjisで入れる。
• .bat_tの中で使うテーマの変数は、conf.pyの中でシフトjisにエンコードしておく 

普通は、こんなことしないと思うのですが、Sphinxで出力されたhtml側でボタンをクリックすると、大元のソースディレクトリの上位のフォルダで、make htmlしてくれる仕組みを作ろうとした際に、起きました。