nikkie-ftnextの日記

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

make htmlだけじゃない！？ Sphinxのビルドコマンドには make singlehtml というものもあるんです！

Sphinx

はじめに

先輩、飲みます？ nikkieです。

Python Boot Camp（a.k.a. pycamp）のライディングページをSphinxで作って得た知見をアウトプットするシリーズです。

このページ、HTMLなのでmake htmlでビルドしてると思うじゃないですか〜1。
実はmake singlehtmlを使うという工夫2をしてるんです！

目次

ドキュメント変換ツールSphinx

Sphinx（スフィンクス）は、あるルールに従って記述されたテキストファイルを、HTMLやPDFなどの形式に変換するドキュメント変換ツールです。

『Sphinxをはじめよう 第3版』（1章）より

pycampランディングページはreStructuredText（reST）というルールに沿って書いたテキストファイル群をHTMLの形式に変換しています。
HTMLをGitHub Pagesでホストして、Webに公開しています。

Sphinxはsphinx-quickstartでプロジェクトを初期設定できます3。
そのときにMakefileも作られます。
このMakefileを使ってmake htmlとすると、reSTファイルがHTMLに変換されます！（＝reSTからHTMLをビルド）

SphinxのMakefileの秘密

SphinxのMakefileはsphinx-buildというコマンドをラップしているんです！

make htmlはsphinx-build -M htmlと渡ります4。
-Mオプションとは別に、ビルダーを指定する-bオプションもあります（-Mは-bのAlternative（＝-bに取って代わるもの）という説明です）。
ドキュメントによると-Mオプションは-bオプションで指定できるビルダーに、いくつかのビルドパイプラインを追加したものです（latexpdfなど）。

singlehtmlビルダー

-bオプションには（よく使われるhtmlの他にも）さまざまなビルダーがあります。
その1つがsinglehtmlです5。

すべてのコンテンツが含まれる、単一のHTMLを生成します。（sphinx-buildのドキュメントより）

pycampのランディングページは1枚に情報を集約している6ので、ドキュメントで偶然singlehtmlを見つけたときに「これだ！」と思いました。

singlehtmlビルダーの実装はSingleFileHTMLBuilderです。

SingleFileHTMLBuilderをはじめとするBuilderクラスのドキュメントを読むと、name属性がsphinx-buildの-bオプションに対応しています。

過去の記事との関連

pycampランディングページの実装（reSTファイル群）はGitHubで公開しています。

reSTファイルは細かく分割し、includeディレクティブを活用しています7。
分割したファイルは*.rst.txtとして、以下の記事で取り上げたwarningが生じないようにしています。

もう一つ別の話題を。
SingleFileHTMLBuilderのformat属性の値は"html"です。
つまり、GitHub Pagesで公開するときはsphinx.ext.githubpagesが使えます！

終わりに

pycampランディングページで使っているmake singlehtmlを紹介しました。

本記事執筆中に偶然知ったのですが、とほほのPython入門でも取り上げられています！（「複数HTML以外の形式にビルドする」）

「単一のHTML生成の使いどころだ！」と気付いたらぜひ使ってみてください。

  1. ここが俺ガイルのいろはすっぽいなと思ったので、今回の挨拶はいろはすです！　ちゃんとあやねるの声で脳内再生してくださいね、先輩↩
  2. https://github.com/pyconjp/pycamp.landing_page/blob/4b57021eb2a3d1d50b6d9a924050c1545a461f39/.github/workflows/publish.yml#L24↩
  3. https://www.sphinx-doc.org/ja/master/man/sphinx-quickstart.html↩
  4. 手元のMakefileの中を見てもよいですし、元となるテンプレートは https://github.com/sphinx-doc/sphinx/blob/v5.3.0/sphinx/templates/quickstart/Makefile.new_t#L20 と思われます↩
  5. -Mオプションには-bオプションのビルダーも指定できるので、もちろんsinglehtmlも指定できます↩
  6. ペライチで作っていたサイト（＝ページ1枚）を移行したいという背景があり、nikkieが「まかせて！」と取り組みました↩
  7. 例えば https://github.com/pyconjp/pycamp.landing_page/blob/4b57021eb2a3d1d50b6d9a924050c1545a461f39/source/index.rst （Rawで見てみてください）↩