SphinxでPlantUMLやblockdiagを書く用のDocker


# 概要

[Sphinx](http://www.sphinx-doc.org/)だけなら、コマンドライン一発で入るご時世です。

```shell-session
pip install sphinx
```
が、そこで[PlantUML](http://plantuml.com/)で書いた図も入れたいね、となるとGraphvizやJavaが必要になってきます。
もっとも、それすらyumやapt-getすればいいという話なんですが、
ビルド環境の調達に時間をかけるのは面倒だ！、CIと組み合わせて使いたいという諸兄（特に自分）用にDockerにしてみた。

あいつの環境でビルドしたHTMLだとレイアウトが崩れるのはなぜだ！とかを無くしたいわけです。
CIとの連携用にイメージ化しておくと何かと都合が良いのでは、ということです。

Sphinxと他の拡張をいれたDockerと、gitlabと組み合わせて使う場合の例を紹介します。

# コンテナに入れたもの

すぐにsphinx-buildしたいので、一式入れておきました。
PlantUMLも良いけど、blockdiagの方がしっくりくるときが多いような気がします。
クラス図を入れたいときにはPlantUMLが重宝するので、両方入れることにしました。

- Sphinx 1.4.9（2016/11/24時点での最新。もうすぐ1.5が出るらしい。[sphinxjp.slack.com](https://sphinxjp.slack.com/)より）
- Sphinxから使えるPlantUML([sphinxcontrib-plantuml](https://pypi.python.org/pypi/sphinxcontrib-plantuml))
- Sphinxから使えるblockdiag([sphinxcontrib-blockdiag](http://blockdiag.com/ja/blockdiag/sphinxcontrib.html))
- blockdiagで日本語使いたいとき用日本語フォント(TakaoFonts)
- bootstrap4対応の[HTML Theme](http://myyasuda.github.io/sphinxbootstrap4theme/)

# conf.py例

PlantUMLやblockdiagを使う、という前提で関連する部分を紹介します。

```py3
import os

extensions = [
  'sphinxcontrib.plantuml',
  'sphinxcontrib.blockdiag',
  'sphinxcontrib.seqdiag',
  'sphinxcontrib.nwdiag',
  'sphinxcontrib.actdiag'
]

# Fontpath for blockdiag (truetype font)
blockdiag_fontpath = '/usr/share/fonts/TakaoFonts/TakaoPGothic.ttf'

plantjar = os.getenv('PLANTUML')
plantuml = 'java -jar %s' % plantjar
```

日本語を含まないblockdiagであれば、フォント指定は不要です。

PlantUMLの場合はjarファイルのパスが必要なので、これを書きます。
Dockerfile内にjarの場所を環境変数として書いてあるので、os.getenvでとるようにしました。

# ビルド使用例

次のように、カレントのsourceフォルダ以下にrstのソースがある構成と仮定します。

```text
.
└─source
        conf.txt
        index.rst(などなど）
```

カレント以下にあるsourceフォルダを指定して、カレント直下にbuildフォルダに出力する例です。

```shell-session
docker run --rm -v `pwd`:/tmp/sphinx  tsgkadot/sphinx-plantuml \ 
       sphinx-build -b html /tmp/sphinx/source /tmp/sphinx/build
```

ビルド時のコンソールの例です。

```shell-session
Unable to find image 'tsgkadot/sphinx-plantuml:latest' locally
latest: Pulling from tsgkadot/sphinx-plantuml

8cf4eb2be1b3: Pull complete 
789c09b3f2c2: Pull complete 
63180e8e234a: Pull complete 
34cccba98f83: Pull complete 
a96ccc590e39: Pull complete 
Digest: sha256:c340cd32836d1bbeecc35ab0ab0b715cb3537e49c802628b1735f13da771e7e8
Status: Downloaded newer image for tsgkadot/sphinx-plantuml:latest
Running Sphinx v1.4.9
making output directory...
loading pickled environment... not yet created
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 6 source files that are out of date
updating environment: 6 added, 0 changed, 0 removed
reading sources... [ 16%] actdiag
reading sources... [ 33%] blockdiag
reading sources... [ 50%] index
reading sources... [ 66%] nwdiag
reading sources... [ 83%] plantuml
reading sources... [100%] seqdiag

looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [ 16%] actdiag
writing output... [ 33%] blockdiag
writing output... [ 50%] index
writing output... [ 66%] nwdiag
writing output... [ 83%] plantuml
writing output... [100%] seqdiag

generating indices... genindex
writing additional pages... search
copying static files... done
copying extra files... WARNING: html_static_path entry '/tmp/sphinx/source/_static' does not exist
done
dumping search index in English (code: en) ... done
dumping object inventory... done
build succeeded, 1 warning.
```


# CIとの組み合わせ例

例えば、Gitlab Runnerと組み合わせて、コミットされたらビルドして、gItlab.ioに公開する場合の.gitlab-ci.ymlの例です。

```yaml
image: tsgkadot/sphinx-plantuml

stages:
  - build

pages:
  stage: build
  script:
    - pip install -r requirements.txt -U
    - sphinx-build -b html ./source public
  artifacts:
    paths:
      - public
  tags:
    - docker
```

オンプレで立てたgitlabで使えば、githubやrtdに公開できないような文書作成の自動化などに使えるかな、と。

実際にビルドしてみた例は[こちら](https://tsgkdt.gitlab.io/sphinx-plantuml/)。