先日GitHubで嬉しいアップデートが行われ、
masterリポジトリの/docs以下をGitHub Pagesで公開できるようになりました。
これまでGitHub Pagesを利用するにはgh-pagesブランチを作成する必要がありましたが、プロジェクトのソースコードと一緒にドキュメントを管理できようになったのはかなり嬉しいです!
そこで今回は、以前書いたAndroidアプリをDockerでビルドする記事をもとに
ドキュメント生成ツールであるSphinxのビルドをDockerでやってみました。
これでプロジェクト用のドキュメントを作ってじゃんじゃん公開していきましょう。
Sphinxとは
SphinxはPython製のドキュメント生成ツールです。
ドキュメント生成ツールとしてはかなり有名でして、Pythonの公式ドキュメントでも利用されています。
基本的なドキュメント作成の流れとしては、
- sphinxをインストール
sphinx-quickstart
コマンドで雛形作成- reStructuredTextでドキュメントを編集
make html
などのコマンドで整形済みドキュメントを作成
となっていて、プラグインや外部ツールとの連携で、reStructuredTextでなくMarkdownで書くことができたり、htmlでなくPDFでの出力ができたりもします。
日本語での詳しい使い方はこちらにあります。
DockerでSphinxドキュメントをビルドする
基本的な構成は前回と同じです。(というかほぼそのまま流用)
ディレクトリ構成はこんな感じ。
├── Dockerfile
├── Makefile
├── README.md
├── _build // ビルド後の成果物
│ ├── doctrees
│ └── html
├── build.sh
├── doc // Sphinxのドキュメントファイル
Dockerfileで前回と違う点としては、ビルド対象のソースはGitHubから取得するのではなく、ローカルのデータを使うようにしています。
FROM ubuntu:16.04
RUN apt-get update -y && apt-get upgrade -y
RUN apt-get install -y python-sphinx make
COPY doc/ /root/
COPY build.sh /root/
CMD ["/bin/sh", "/root/build.sh"]
続いてMakefileはこちら。
前回同様ビルドした成果物をホストマシンにコピーしてます。
date=$(shell date +%s)
docker-html: Dockerfile
docker build -t rhoboro/sphinx-doc:0.1 .
docker run --name="sphinx-doc-$(date)" rhoboro/sphinx-doc:0.1
docker cp sphinx-doc-$(date):/root/_build/ .
docker rm sphinx-doc-$(date)
最後にbuild.sh。 これはビルドしてるだけですね(笑
cd /root && make html
余談
先日、自分のPCでは問題なくsphinxドキュメントのビルドができていたのに、会社のPC(いつ入れたかわからないsphinxが入ってた)ではビルドできないということがありました。
そのときもDockerでビルドできるようにしておいたおかげで、大きな問題にならず作業を進めることができました。
そんなこともあり、やはりマシンの環境に依存しないというのはDockerのすごく大きなメリットだなぁと感じましたので、みなさんもDocker使っていきましょう! 特に今回のはAndroidアプリと違って必要なツールはSphinxだけですし、そのまま使える機会も多いと思います。 いいですよ、Docker。