はじめに
Act-4、よかった。想いのこもったツイート見るたび泣いてます。nikkieです。
このところSphinx熱が再燃しており、本日もSphinxネタです。
目次
- はじめに
- 目次
- Sphinxの自作拡張におけるTranslator
- 結論：現時点の理解
- Sphinxの拡張
- TranslatorとBuilder
- 『マスタリング docutils』より
- 終わりに
- P.S. わかりやすかった記事
Sphinxの自作拡張におけるTranslator
SphinxでビルドしたHTMLの中の外部リンクを、ブラウザの新しいタブで開くように設定する拡張を公開しています。
参考にしたのは以下の実装1。
def setup(app): app.set_translator("html", NewTabLinkHTMLTranslator)
「このset_translator()ってなんだろう？」と疑問に思いました。
結論：現時点の理解
- SphinxのTranslatorは、ドキュメントツリーの出力フォーマットへの変換を担うクラス
- 例：自作拡張のTranslatorは、
<a>タグの変換をカスタマイズしている - Translator自体はDocutilsが提供する概念
- 例：自作拡張のTranslatorは、
set_translator()メソッドは、BuilderにTranslatorクラスを設定する- Builderは出力形式ごとにある（例：HTMLのBuilder）
- 出力形式ごとに出力フォーマット変換を設定できる
Sphinxの拡張
上記のようなsetup()関数を持つモジュールがSphinx拡張です。
setup()関数の引数appはapplicationオブジェクト。
https://www.sphinx-doc.org/ja/master/extdev/index.html#important-objects
今回気になった点は、Sphinxインスタンスのset_translator()メソッドということですね。
TranslatorとBuilder
Translator
set_translator()メソッドより
https://www.sphinx-doc.org/ja/master/extdev/appapi.html#sphinx.application.Sphinx.set_translator
Register or override a Docutils translator class.
TranslatorはDocutilsの概念です（後述）。
set_translator()メソッドは2つの引数で呼ばれます：
- name: TranslatorのためのBuilderの名前
- translator_class
つまり、TranslatorとBuilderを設定するわけです。
Builder
quickstartしている場合、make htmlのhtmlがBuilderの指定です2。
Builderの持つ属性について
https://www.sphinx-doc.org/ja/master/extdev/builderapi.html
- name: Builderの名前（例：html, singlehtml）
- default_translator_class
default translator class for the builder. This can be overridden by set_translator().
BuilderはデフォルトのTranslatorを持つわけですね。
そして、app.set_translator()はBuilderのTranslatorを設定している。
具体のBuilderを見てみます。
make htmlで指定しているのは、StandaloneHTMLBuilder
https://www.sphinx-doc.org/ja/master/usage/builders/index.html#sphinx.builders.html.StandaloneHTMLBuilder
ソースを見ると
class StandaloneHTMLBuilder(Builder): default_translator_class = HTML5Translator
つまり、自作拡張の実装では、StandaloneHTMLBuilderのdefault_translator_classをHTML5TranslatorからNewTabLinkHTMLTranslatorに変えたわけです。
『マスタリング docutils』より
Translatorについて、6章が詳しいです。
- WriterはTranslatorを決定する
- WriterはTranslatorを呼び出して、ドキュメントツリーを出力フォーマットに変換
- Translatorはドキュメントツリーの出力フォーマットへの変換を担うだけ
終わりに
自作拡張のapp.set_translator("html", NewTabLinkHTMLTranslator)が何をやっているのか見てきました。
"html"はHTML用のBuilderを指定- HTML用のBuilderに
NewTabLinkHTMLTranslatorを設定- このTranslatorが出力フォーマット変換を担う
つまり、HTMLを出力するときの（HTMLの）フォーマット変換を指定しているわけですね3。
Sphinx拡張のドキュメントは散らばっている印象ですが、このエントリを機につながりが少し見えてきた感覚です。
『マスタリングdocutils』に知見をまとめていただいたことに感謝です
P.S. わかりやすかった記事
用語の整理がわかりやすかったです。
Docutils を拡張し、ドキュメントを構成できるようにしたもの
Sphinx用語のBuilderは
パースされたドキュメントを入力として、ファイルの出力やなんらかのデータ処理を行うクラス。docutils の Writer, Translator を利用したり拡張したりしている。
Docutils用語のTranslatorは
doctree 内のノードを出力形式ごとのデータに変換するクラス。
