DockerでSphinxを使う¶
- 更新日
2020-09-25
はじめに¶
Sphinx をDockerで使うためのDockerイメージを作成し hnakamur/sphinx - Docker Hub に公開しています。
このDockerイメージは ブロック図生成ツール blockdiag と UML作成ツール PlantUML も使えるように対応するSphinx拡張を組み込んであります。
以下ではこのDockerイメージを使ってSphinxを使う手順を説明します。
Docker ID作成¶
WindowsとmacOSの場合はDocker for Windows, Docker for MacをダウンロードするのにDocker IDというユーザIDの登録が必要になります。 Linuxでも自作のDockerイメージを Docker Hub で公開するにはDocker IDが必要になります。
Docker ID accounts のRegister for a Docker IDの手順で登録してください。
Dockerのセットアップ¶
Windows¶
Install Docker for Windows の手順に従ってインストールします。
macOS¶
Install Docker for Mac の手順に従ってインストールします。
Linux¶
ディストリビューションに応じて下記のインストール手順でインストールします。
Dockerの共有フォルダのセットアップ¶
Windowsでは共有フォルダのセットアップが必要です。
タスクトレイのDockerアイコンを右クリックしてポップアップメニューを開き[Settings]を選択。
左のリストで[Shared Drives]を選択。
右のリストで共有フォルダを使いたいドライブを選択して[Shared]の列のチェックボックスを選択し[Apply]ボタンを押す。
F-Secure をお使いの場合は Allowing file sharing with F-Secure firewall turned on - F-Secure Community の手順でファイアウォール設定を変更する必要があります。
Sphinxドキュメントプロジェクトの作成¶
Sphinxドキュメントプロジェクトの作成には sphinx-quickstart を使います。
hnakamur/sphinx のDockerイメージにはこれをラップしたスクリプト my-sphinx-quickstart が含まれています。
blockdiagやPlantUMLのSphinx拡張を組み込み、テーマは Sphinx Themes で紹介されていた solar-theme を使うようになっています。
Windows¶
ドキュメントプロジェクトを作成し、コマンドプロンプトを開いてそこに移動し、以下のコマンドを実行します。
docker run --rm -it -v "%cd%:/documents" hnakamur/sphinx my-sphinx-quickstart
プロジェクト名、著者名、リリース番号を聞かれますので入力します。
あるいは以下のようにオプションで指定することも可能です（コマンドが長くて折り返して表示されていると思いますが1行で入力してください。以下全てのコマンドも同様です）。
docker run --rm -it -v "%cd%:/documents" hnakamur/sphinx my-sphinx-quickstart -p "YourProjectName" -a "John Doe <john.doe@example.com>" -r 1.0
macOS¶
ドキュメントプロジェクトを作成し、ターミナルを開いてそこに移動し、以下のコマンドを実行します。
docker run --rm -it -v "$PWD:/documents" hnakamur/sphinx my-sphinx-quickstart
プロジェクト名、著者名、リリース番号を聞かれますので入力します。
あるいは以下のようにオプションで指定することも可能です。
docker run --rm -it -v "$PWD:/documents" hnakamur/sphinx my-sphinx-quickstart -p "YourProjectName" -a "John Doe <john.doe@example.com>" -r 1.0
Linux¶
ドキュメントプロジェクトを作成し、ターミナルを開いてそこに移動し、以下のコマンドを実行します。
docker run --rm -it -v "$PWD:/documents" -e SWITCH_USER=1 -e LOCAL_UID=$(id -u $USER) -e LOCAL_GID=$(id -g $USER) hnakamur/sphinx my-sphinx-quickstart
プロジェクト名、著者名、リリース番号を聞かれますので入力します。
あるいは以下のようにオプションで指定することも可能です。
docker run --rm -it -v "$PWD:/documents" -e SWITCH_USER=1 -e LOCAL_UID=$(id -u $USER) -e LOCAL_GID=$(id -g $USER) hnakamur/sphinx my-sphinx-quickstart -p "YourProjectName" -a "John Doe <john.doe@example.com>" -r 1.0
ドキュメントのビルド¶
ドキュメントを書いて保存したら以下の手順でビルドします。
Windows¶
ビルドには以下のコマンドを実行します。
docker run --rm -it -v "%cd%:/documents" hnakamur/sphinx make html
あるいは以下のコマンドでもビルドできます。
docker run --rm -it -v "%cd%:/documents" hnakamur/sphinx sphinx-build -b html source build
macOS¶
ビルドには以下のコマンドを実行します。
docker run --rm -it -v "$PWD:/documents" hnakamur/sphinx make html
あるいは以下のコマンドでもビルドできます。
docker run --rm -it -v "$PWD:/documents" hnakamur/sphinx sphinx-build -b html source build
Linux¶
ビルドには以下のコマンドを実行します。
docker run --rm -it -v "$PWD:/documents" -e SWITCH_USER=1 -e LOCAL_UID=$(id -u $USER) -e LOCAL_GID=$(id -g $USER) hnakamur/sphinx make html
あるいは以下のコマンドでもビルドできます。
docker run --rm -it -v "$PWD:/documents" -e SWITCH_USER=1 -e LOCAL_UID=$(id -u $USER) -e LOCAL_GID=$(id -g $USER) hnakamur/sphinx sphinx-build -b html source build
ドキュメントを編集しつつ自動ビルド¶
sphinx-autobuild を使うと、ドキュメントを編集し保存したら自動でビルドを実行してブラウザをリロードできます。
Windows¶
コマンドプロンプトを開いてドキュメントプロジェクトのディレクトリに移動し以下のコマンド実行します。
docker run --rm -it -v "%cd%:/documents" -p 8000:8000 hnakamur/sphinx sphinx-autobuild --host 0.0.0.0 source build/html
ブラウザで http://127.0.0.1:8000 を開くとビルドされたドキュメントを確認できます。ポートを変えたい場合は -p オプションのコロンより前の番号を変えてください。
本来ならこれだけで良いのですが、Docker for Windowsの制約でWindows上のファイルを保存しても変更通知がコンテナに伝わらず自動ビルドが走らないという問題があります。
回避策として
hnakamur/docker-windows-volume-watcher
を使います。
hnakamur/docker-windows-volume-watcherのReleasesページ
から docker-windows-volume-watcher をダウンロードしてください。
もう1つコマンドプロンプトを開き以下のコマンドを実行してください。
docker-windows-volume-watcher.exe -ignoredir .git;build
これでドキュメントのファイルを保存すると自動ビルドが走りブラウザがリロードされます。
macOS¶
ターミナルを開いてドキュメントプロジェクトのディレクトリに移動し以下のコマンド実行します。
docker run --rm -it -v "$PWD:/documents" -p 8000:8000 hnakamur/sphinx sphinx-autobuild --host 0.0.0.0 source build/html
ブラウザで http://127.0.0.1:8000 を開くとビルドされたドキュメントを確認できます。ポートを変えたい場合は -p オプションのコロンより前の番号を変えてください。
Linux¶
ターミナルを開いてドキュメントプロジェクトのディレクトリに移動し以下のコマンド実行します。
docker run --rm -it -v "$PWD:/documents" -p 8000:8000 -e SWITCH_USER=1 -e LOCAL_UID=$(id -u $USER) -e LOCAL_GID=$(id -g $USER) hnakamur/sphinx sphinx-autobuild --host 0.0.0.0 source build/html
ブラウザで http://127.0.0.1:8000 を開くとビルドされたドキュメントを確認できます。ポートを変えたい場合は -p オプションのコロンより前の番号を変えてください。
ビルドしたドキュメントをGitHub Pagesで公開¶
以下のコマンドを実行するとビルドしたHTMLをGitHub Pagesで公開できます。
git subtree push --prefix build/html/ origin gh-pages
なお、これを行うためにはbuild以下のファイルもmasterブランチでコミットしておく必要がありました。
また、GitHub Pagesを使うための設定として、一度 gh-pages ブランチにプッシュした後でGitHubのプロジェクトの[Settings]のGitHub PagesセクションでSourceの下のドロップダウンで[gh-pages branch]を選んで[Save]ボタンを押す必要があります。