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

はじめに

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

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

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

目次

• はじめに
• 目次
• ドキュメント変換ツールSphinx
• SphinxのMakefileの秘密
• singlehtmlビルダー
• 過去の記事との関連
• 終わりに

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

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

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

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

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

SphinxのMakefileの秘密

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

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

singlehtmlビルダー

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

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

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

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

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

過去の記事との関連

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

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

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

終わりに

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

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

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