概要
Sphinxだけなら、コマンドライン一発で入るご時世です。
pip install sphinx
が、そこでPlantUMLで書いた図も入れたいね、となると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より）
- Sphinxから使えるPlantUML(sphinxcontrib-plantuml)
- Sphinxから使えるblockdiag(sphinxcontrib-blockdiag)
- blockdiagで日本語使いたいとき用日本語フォント(TakaoFonts)
- bootstrap4対応のHTML Theme
conf.py例
PlantUMLやblockdiagを使う、という前提で関連する部分を紹介します。
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のソースがある構成と仮定します。
.
└─source
conf.txt
index.rst(などなど）
カレント以下にあるsourceフォルダを指定して、カレント直下にbuildフォルダに出力する例です。
docker run --rm -v `pwd`:/tmp/sphinx tsgkadot/sphinx-plantuml \
sphinx-build -b html /tmp/sphinx/source /tmp/sphinx/build
ビルド時のコンソールの例です。
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の例です。
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に公開できないような文書作成の自動化などに使えるかな、と。
実際にビルドしてみた例はこちら。