Sphinxの環境構築で楽をする: HTMLとPDFを生成するDockerコンテナを作った

Diary
Sphinxの環境構築で楽をする: HTMLとPDFを生成するDockerコンテナを作った
Page content

勢い余って直構築 → Dockerでやろう

ドキュメンテーションジェネレータの「Sphinx」を詳しく説明している次の記事を見つけた。

Sphinxは以前から注目していたツールで、使いこなしてみたくなり、記事をなぞる形で環境構築を始めた。reStructuredTextではなくMarkdown形式で原稿を書くようにして、Mermaid記法への対応を試してみたり、Mermaidの図はLaTeXに持っていきにくそうだから図の記法をPlantUMLへ切り替えて、PlantUMLを描画するためのJava環境を用意し、LaTeXを経由したPDFファイルの中に図が描けていることを確認して……と、いくつかの問題を時間をかけてやっと乗り越えられそうだと思ったときに、気づいた。

昨今、Sphinxみたいなややこしいソフトウェアの環境構築は、Dockerを使って仮想的に行う潮流だった。ということは、この場合もDockerコンテナを用意すると便利では？ (そういえば拙作LibLibでやってたなあ)

GitHubに公開してます

上記の着想から数日を費やし、Sphinx環境のDockerコンテナをコマンド一発で用意できるファイル一式を完成させて、mah-jp/sphinx-docker_gen-html-pdfというリポジトリ名でGitHubにアップロードした。

Sphinxでのドキュメンテーションを始める際、Dockerの力を使うと圧倒的に楽ができる。そのような時にはよかったらこのリポジトリをcloneしてみてください。

おまけ: 完成までのTry and Errorの軌跡

上記リポジトリのファイル一式を完成させるまで、いくつかのエラーを解決する必要があった。特にCase-3などはウェブ情報が少なくて、(M1 MacのDockerをx86-64として動かしてみてエラーの変化を調べたりなど) なかなかの試行錯誤を伴う道のりだった。誰かの参考になるかもしれないのでメモを残します。

Case-1.

/docs/sample.rst:00: WARNING: epstopdf command 'epstopdf' cannot be run

  • texlive-font-utilsパッケージをインストールする

Case-2.

WARNING: command 'mmdc' cannot be run (needed for mermaid output), check the mermaid_cmd setting

  • npmパッケージをインストールした上で、npm install -g @mermaid-js/mermaid-cliを実行する

Case-3.

b'\nError: Failed to launch the browser process!\nrosetta error: failed to open elf at /lib64/ld-linux-x86-64.so.2\n

これはM1のmacOS環境 (Ventura 13.6.7) で遭遇した。Dockerイメージのアーキテクチャはarm64のはずなのに、なぜだか「Rosetta」や「x86-64」がエラーメッセージに登場する。わけがわからない。

  • 参考リンク: 具体的には無し (いくつかの情報を突き合わせての私なりの推理だが、Puppeteerがブラウザを発見できない場合、Puppeteerがx86-64版のブラウザを勝手にインストールしてしまうのだろうか)
  • chromiumパッケージをインストールする
  • conf.py: mermaid_params = ['-p', 'puppeteer-config.json']を追加
  • puppeteer-config.jsonを次の内容で新規作成する
    {
  "executablePath": "/usr/bin/chromium"
}

Case-4.

b'\nError: Failed to launch the browser process!\n[0000/000000.000000:ERROR:zygote_host_impl_linux.cc(99)] Running as root without --no-sandbox is not supported.

参考リンク