sphinxcontrib-budoux

概要

sphinxcontrib-budoux は、SphinxプロジェクトからHTMLを生成する際に、違和感なく改行をを差し込めるようにするSphinx拡張です。

基本的な挙動説明

注釈

細かい設定をしないケースでの挙動です

SphinxでのHTML生成時に処理を挟み込み、設定で指定されているタグに対して、 以下の処理を行っています。

1. 子要素の分割

2. 子要素のうちテキストの要素に対して、BudouXによる文字列分割を実施

3. 分割された文字列を wbr タグが間に置かれるように再構成

4. 上記で再構成された子要素群に上書き

5. 対象要素に style 属性で wbr タグに対する振る舞いを指定

設定可能なオプション

これらは、いずれも conf.py に指定することで動作挙動を変更することが出来ます。

budoux_targets

sphinxcontrib-budoux による処理対象としたいタグ名の一覧。デフォルトでは ["h1"] (ページタイトル部のみ)。

他の要素などにも適用したい場合は、ここで複数の要素を指定することが可能です。（例： ["h1", "h2", "p"] ）

budoux_split_tag

文字列分割時に差し込みたい要素名。

例えば、「画面状態に関わらず何があろうと改行したい」といった場合は br を指定することで実現できます。

budoux_split_style

上記 budoux_targets で検出したタグに対して割り当てられる style 属性の内容。

標準では適切なタイミングで改行が入るような設定を指定しています。

利用時における注意事項

「ページ内で要素を探索して処理」「対象要素全てに対して style 属性を付与 」というシンプルな実装をしている関係上、 budoux_targets の指定内容によってはパフォーマンス劣化が起こる可能性があります。

• 探索数増大による処理時間増加

• style 属性追加によるコンテンツサイズ増加

また、以下の理由により、ブラウザが「実際にどのタイミングで改行するか」の正確なコントロールは出来ません。

• BudouXで分割した全てにタグを差し込んでいる（この調整を行う予定がない）

• 対象となった全要素に対して、同じ style 属性を適用している

• style 属性の他に改行タイミングを決定する要素が存在する可能性が高い

最後に、あくまで「Sphinxが生成するHTML」に対して処理を実行するため、直感に反する動きをする可能性があります。

具体的には、リストで記述したソースはHTMLとしては ol > li > p > (コンテンツ) となっています。 そのため、 budoux_targets 内で li の指定をしても動作せず、 p の指定が必要となる可能性があります。（ただし未確認）