====================
sphinxcontrib-budoux
====================

概要
====

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

基本的な挙動説明
================

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

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

#. 子要素の分割
#. 子要素のうちテキストの要素に対して、BudouXによる文字列分割を実施
#. 分割された文字列を ``wbr`` タグが間に置かれるように再構成
#. 上記で再構成された子要素群に上書き
#. 対象要素に ``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`` の指定が必要となる可能性があります。（ただし未確認）