Sphinx LaTeX Translatorを読もう

Sphinx LaTeX Translatorを読もう

数年前、ドキュメント系は何もかもreSTで書いていた時期、 卒研の中間報告をreSTで書いたのをSphinxでにして 出していたことを思いだした。

中間報告用のスタイルファイルが提供されていたが、 sphinx.styの設定と競合するところがあって苦労した。当時は.styや.clsの中身を読める程 にも習熟していなかったから試行錯誤して改造しまくって、再利用性が全く無くて失敗だった。

過去の話は置いておいて、 SphinxのLaTeX出力を改造するなら「どの段階で」「どの出力を」いじるのかを考える必要がある。 Sphinxの出力に手を入れないのなら、のクラス・スタイルファイルをいじる必要が ある。簡単な調整なら適当に目についたエラー箇所を書き換えれば 何とかなるが、使い勝手を考えるとsphinx.styの中で定義されている命令群などをしっかり把握する必要がある。

その中間での課題として 出力で何が辛いかといえば、「自分のドキュメントでは使わないものも決め打ちで書き込まれてしまう」ことである。この書き込まれる内容に関わるのがwriter、そしてそこで利用されるTranslatorである。

買って応援Sphinx

writersやらbuildersやらはdocutilsの構造の話で、この詳細が知りたいのであれば

がなんと無料化されたので是非ダウンロードして読んでほしい。

Sphinxでの拡張は既存の拡張を参考にすると作りやすい。 そのための拡張の読み方について事例を交えて解説されている

がたったの1000JPY！

writers/latex.py

大雑把にはこれはデフォルト設定のプリアンブル、conf.pyで設定可能なパラメータのデフォルト、 パラメータによる設定の分岐項目と固有のテーブル処理など、 そしてTranslatorを呼び出し書き込みを行うWriterと各マークアップのNodeをどう処理するかを記述したTranslatorで構成される。LaTeXWriterで読みこまれるときにデフォルトのプリアンブルをどうにかしておかないと、ビルド時に若干アレなプリアンブルが読みこまれてしまう。

sphinxhowtoとsphinxmanualとlatex_theme

HTMLに比べ貧弱とも言えるSphinxの出力。これは 「のことはよくわかんないけどいい感じに望んだ出力がほしい」という素朴な欲求 の悪魔合体であるところ*1のhowtoとmanualとLaTeXBuilder（ここではWriter, Translatorを含む）の絡み合いによるところが大きいのではないか。 前回記事にしたように、側としてsphinxhowto.clsとsphinxmanual.clsで設定されていることは意外と少ない。個人の意見として、先ず「LaTeXBuilderがやりすぎ」であるのが現在の「いい感じにしたいけどよくわからん」の原因ではなかろうかと思う。つまり sphinx/writers/latex.pyなんてエンドユーザが読みにいかなさそうなところに書かれたデフォルト設定の量の多さが今となってはよくないのではないかと。

昔に比べ、現在はLiveの整備によって充実したのクラス・スタイルファイルを簡単に利用できるようになっている。これは人、人がを書けるようになったことを意味しないが、しかしひっそりとした場所に決め打ちになっているコードとの相性はよくなさそうである。クラスファイル・エンジンの差を吸収する方針は良いとして、の話をPython側でなんとかしようとしすぎではないか。

クラス・スタイルファイルが様々な点で独立である以上、先ずはhowtoとmanualという、いってみればthemeにすぎないものと密結合なLaTeXBuilder特に中身であるLaTeXTranslatorを 構築し直すことが必要なのかもしれない。年始くらいに何かしらできるように頑張る。

記事書いてたら拡張全然書けてへんな。jlreq.clsはエンドユーザ用のオプションだけでも設定項目異常や……。