SphinxドキュメントをDockerでビルドする

Posted by rhoboro on 2016-09-04

先日GitHubで嬉しいアップデートが行われ、 masterリポジトリの/docs以下をGitHub Pagesで公開できるようになりました。
これまでGitHub Pagesを利用するにはgh-pagesブランチを作成する必要がありましたが、プロジェクトのソースコードと一緒にドキュメントを管理できようになったのはかなり嬉しいです!

そこで今回は、以前書いたAndroidアプリをDockerでビルドする記事をもとに
ドキュメント生成ツールであるSphinxのビルドをDockerでやってみました。
これでプロジェクト用のドキュメントを作ってじゃんじゃん公開していきましょう。

Sphinxとは

SphinxはPython製のドキュメント生成ツールです。
ドキュメント生成ツールとしてはかなり有名でして、Pythonの公式ドキュメントでも利用されています。

基本的なドキュメント作成の流れとしては、

  1. sphinxをインストール
  2. sphinx-quickstartコマンドで雛形作成
  3. reStructuredTextでドキュメントを編集
  4. 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。