最近作ったりしていたSphinx拡張+αの簡単な紹介をする(2024年04月編)
以前にこんな記事を書いていました。
ごくごく直近でアクティブだった訳ではないのですが、ちょっとした棚卸しを兼ねて「こんなSphinx拡張作ってみてた」という紹介をします。
まえがき
- 前回同様に「導入すると何が出来るか」を主眼に紹介します。
- ライブラリ紹介時に記載するURLへ遷移するとREADMEを参照できるので、インストール方法などは個別に見てください。
紹介本編
atpshinx-color-text
Sphinxに色指定を可能にするロールを付与する拡張です。
やってることは、「:color:色指定:」を付与した箇所に、CSSのインラインスタイルでcolorを付与するだけです。
.. 「な」だけ赤くなります
ひぐらしの :color:red:`な` く頃に
atsphinx-mini18n
以前も作った sphinx-contrib-mixed-builderの亜種です。
sphinx-intl等で準備したi18n用の設定を利用して、単一ビルドで複数言語のドキュメントをまとめて生成します。
extensions = [
"atsphinx.mini18n",
]
mini18n_default_language = "en"
mini18n_support_languages = ["en", "ja"]
例えば、デフォルトの言語設定がenで、sphinx-intlなどでja向けのpoファイルを用意していると、
make mini18n-htmlを実行するだけで次のアセットを生成できます。
-
/enで始まる英語ドキュメント -
/jaで始まる日本語ドキュメント - 適宜リダイレクトする
/index.html
Read the Docsには複数のドキュメントプロジェクトを束ねてi18n化の対応が可能です。
一方でこの拡張を使うと、GitHub Pagesのような単体アセットしかデプロイ出来ない環境上でもi18nサイトを手軽に展開できます。 [1]
atsphinx-htmx-boost
htmxのhx-boost機能を利用して、お手軽にSphinxドキュメントの体感速度を向上させる拡張です。
（大雑把に書くと）hx-boost属性が付与されたサイト内リンクは、クリック時に画面遷移ではなくbody内の入れ替えを行います。
ドキュメント内部のリンクにこの属性を付与することで、ドキュメントを読む際に発生する待ち時間の軽減を計ることができます。
なお、通常はクリック時に通信が発生するのですが、htmx_boost_preloadを有効にするとpreload拡張もロードしてマウスオーバー時に通信させることも出来ます。
こうすると、クリックしたときにはすでに通知が終わっており、あっという間に画面が変わります。
番外編
atsphinx-helper
Sphinx拡張ではなく、個人的に作った「Sphinx拡張の実装を補助するライブラリ」です。
「このビルダー（この出力をするビルダー）でしか動作させたくない」といったときに、ガードをするデコレーターを定義しています。
from atsphinx.helper.decorators import emit_only
@emit_only(formats=["html"])
def setup_custom_loader(app: Sphinx):
...
def setup(app: Sphinx):
"""Load as Sphinx-extension."""
app.connect("builder-inited", setup_custom_loader)
...
上記の実装をした拡張をconf.pyで有効にしていていると、
仮にmake latexpdfのようなビルダーを実行するとsetup_custom_loaderが実行されなくなります。 [2]
Discussion