nikkie-ftnextの日記

イベントレポートや読書メモを発信

sphinx-revealjsで作ったスライドをGitHub Pagesで公開するときにもsphinx.ext.githubpagesは味方してくれます！

Sphinx

はじめに

「みんな、ウタだよ！」、nikkieです。

先日、愛用しているsphinx.ext.githubpagesを紹介しました。

今回はsphinx-revealjsとsphinx.ext.githubpagesの組合せについて紹介します。

目次

本記事の立ち位置

ここでアウトプットするネタは以下のツイートの詳細版です。

また、この記事自体は、以下の記事のアップデート版となります。

sphinx.ext.githubpagesを使うと何ができて嬉しいのかは、冒頭で示した先日のアウトプットを参照ください。

結論：sphinx.ext.githubpagesも使ったsphinx-revealjs製スライドのデプロイ

Sphinxプロジェクトのconf.pyのextensionsは以下のようになります。

extensions = [
    "sphinx_revealjs",
    "sphinx.ext.githubpages",
]

この設定でmake revealjsすると.nojekyllが作られます🙌

私は、GitHub Pages用のブランチにスライドのHTML一式をpushするGitHub Actionを使っています。

仕組み：sphinx.ext.githubpagesはなぜsphinx-revealjsでも動くのか？

sphinx.ext.githubpagesの実装

https://github.com/sphinx-doc/sphinx/blob/v5.3.0/sphinx/ext/githubpages.py#L13-L14

    if app.builder.format == 'html':
        open(os.path.join(app.builder.outdir, '.nojekyll'), 'wb').close()

sphinx.ext.githubpagesはビルダーのformatが"html"のときに処理をするように実装されています。

Sphinxのビルダー

以下のドキュメントに一覧になっています：

例として、一番上にあるStandaloneHTMLBuilderを見てみましょう。

name属性がビルダーの名前です。

name = 'html'

ビルドコマンドmake htmlはsphinx-buildコマンドをラップしていると理解していますが、これはname属性が"html"のStandaloneHTMLBuilderを指定しているのですね！

format属性はビルダーのアウトプット形式です。

format = 'html'

ここからsphinx.ext.githubpagesはビルダーのアウトプット形式がHTMLのときに処理をすると分かります。

sphinx-revealjsのビルダー

では、sphinx-revealjsのビルダーはどうなっているのでしょうか？
実装を見てみましょう。

https://github.com/attakei/sphinx-revealjs/blob/v2.4.1/sphinx_revealjs/builders.py#L23

class RevealjsHTMLBuilder(StandaloneHTMLBuilder):

RevealjsHTMLBuilderは（上で見た）StandaloneHTMLBuilderを継承しています！
format属性を変更するコードは見つからないので、ベースクラスのStandaloneHTMLBuilderと同様にformat属性は"html"ですね。
つまり、ビルダーのアウトプット形式がHTMLなので、sphinx.ext.githubpagesは処理をします！
これが「sphinx.ext.githubpagesはなぜsphinx-revealjsでも動くのか？」の答えです。

また、RevealjsHTMLBuilderはname属性の値が"revealjs"ですね。
この実装によりmake revealjsコマンドが動くわけですね。

終わりに

sphinx-revealjsとsphinx.ext.githubpagesを組合せて使えることを紹介しました。
conf.pyでsphinx.ext.githubpagesを有効にするだけで、.nojekyllが作られます！（sphinx-revealjsを使っているなら依存するSphinxはインストール済みで、sphinx.ext.githubpagesはSphinxにバッテリーインクルードされています！）
「いいな🤗」と思った方は、ぜひお手元のsphinx-revealjsプロジェクトで試してみてください。

今回はビルダーのドキュメントと合わせて実装を部分的に見に行ってみました。
その中で分かったことの1つですが、make htmlやmake revealjsと渡す引数はビルダーの名なのですね。
小さな秘密が一つ明かされましたー