あめだまふぁくとりー

Boost.Graphとかできますん

Sphinx における日本語文書の不自然な空白を除去する拡張を公開した

Sphinx で日本語文章を書いたドキュメントを HTML として表示すると, 改行箇所やインラインマークアップの前後で空白が表示されてしまいます. 今までは japanesesupport.py を使用していたのですが, pip でインストールできないのが面倒くさかったので同機能の拡張を自作してパッケージ化しました.

pypi.org

japanesesupport.py には色々問題があったため, 一から自作しています.

半角文字間の空白の維持

japanesesupport.py では英単語間で改行を挟むとその英単語間の空白まで除去されてしまいます.

sphinxcontrib-trimblank では除去対象の空白の前後が半角かどうかチェックするようにしています. ASCII コードの範囲だけでチェックすると必要以上に空白が消えてしまうので, 全角となる Unicode の文字範囲を適当に調べて実装しています (この点は改善の余地があると思います).

パラグラフ以外での空白の除去

japanesesupport.py は Docutils の paragraph ノード 直下のテキストしか空白除去の対象にしていません. このため, インラインマークアップ中の改行等が除去されません.

sphinxcontrib-trimblank はテキストを包含できる他のノードも対象にいれています (もちろん, literal_block 等の改行を維持するノードは対象外にしています).

改行とインラインマークアップ前後以外の空白の除去

私は Sphinx で文章を書く場合は日本語と半角英数字との間に空白を入れるようにしているのですが, 以下のような文章を japanesesupport.py で処理すると二つ目の japanesesupport.py の直前の空白は残りますが直後の空白は消えてしまいます.

japanesesupport.py でこの文章を処理すると, 二つ目の japanesesupport.py
の直前には空白があるのに対し, 直後には空白がない文章が生成されてしまう.

f:id:amedama41:20190811173058p:plain
japanesesupport.py での処理結果

sphinxcontrib-trimblankでは一貫性のある文章を出力するため,改行とインラインマークアップ前後以外の空白も除去します.

f:id:amedama41:20190811173116p:plain
sphinxcontrib-trimblank での処理結果

ただし, HTML など特定種別のドキュメントでは日本語と半角英数字との間の空白だけは除去したくない人もいるかと思います. その場合, conf.py に以下のオプションを追加することで日本語と半角英数字間の空白を維持できます.

# html, singlehtml でビルドする場合は半角英数字との間の空白は維持する
trimblank_keep_alnum_blank = ['html', 'singlehtml']

f:id:amedama41:20190811173125p:plain
日本語と半角英数字間の空白を維持した場合の処理結果

ドキュメントの種別に関わらず, 維持したい場合はオプションの値をリストの代わりに True を指定できます.