Help us understand the problem. What is going on with this article?

ReadTheDocsテーマを使用したSphinxのDockerイメージの構築

More than 1 year has passed since last update.

序文

wamw Friday I/O 2日目です。
株式会社ワムウでは、毎週金曜日は 興味がある事柄に取り組み、その成果を何らかの形でアウトプットする日 としています。

最近ドキュメントを書く機会が増えてきて、Markdownで書いたり、Keynoteで書いたり、残念ながらWordで書く必要があったりしていたのですが、色々とダルいのでこれを機にreStructuredTextで書くことに統一しようかなと思った次第であります。

欲しいもの

  • reStructuredTextが簡単にビルドできる
  • ReadTheDocsテーマで吐き出される
  • アウトプット形式はとりあえずHTMLのみ
  • blockdiagが埋め込める
  • とにかくさっくり書ける

と言ったもの。
ドキュメントを公開してどうにかする話は一旦考えません。

作ったもの

以下構築時のログ

方向性としては Docker に alpine で良いのですが、Python入れたりなんやかんやが面倒なのでベースは python:alpine3.6 を使用します。

それでは作っていきましょう。

構築手順

まず立ち上げて

docker run --rm -it python:alpine3.6 sh

コンテナ内で作業しましょう。
apk のアップデート

apk update

次に Sphinx のインストール

pip install sphinx

ReadTheDocs テーマのインストール

pip install sphinx_rtd_theme

blockdiag を使えるように

pip install sphinxcontrib-blockdiag

すると下記エラーが発生します。

  The headers or library files could not be found for zlib,
  a required dependency when compiling Pillow from source.

  Please see the install instructions at:
     https://pillow.readthedocs.io/en/latest/installation.html

上記URIによると blockdiag が依存している Pillow には zliblibjpeg が必要らしいので追加します。

apk add zlib-dev libjpeg-turbo-dev

そして再度 sphinxcontrib-blockdiag のインストール

pip install sphinxcontrib-blockdiag

するとまたエラー

    unable to execute 'gcc': No such file or directory
    error: command 'gcc' failed with exit status 1

gcc ねーよですね、わかります。追加します。

apk add alpine-sdk

そしてふたたび sphinxcontrib-blockdiag のインストール

pip install sphinxcontrib-blockdiag

したら

Installing collected packages: Pillow, webcolors, blockdiag, sphinxcontrib-blockdiag
Successfully installed Pillow-4.2.1 blockdiag-1.5.3 sphinxcontrib-blockdiag-1.5.5 webcolors-1.7

GOOD

良さそうなので動かしてみましょう。
適当なディレクトリを作成して sphinx-quickstart します。

mkdir documents
cd documents
sphinx-quickstart

で、Enter連打します。

/documents # ls -l
total 32
-rw-r--r--    1 root     root           607 Aug  4 05:52 Makefile
drwxr-xr-x    2 root     root          4096 Aug  4 05:52 _build
drwxr-xr-x    2 root     root          4096 Aug  4 05:52 _static
drwxr-xr-x    2 root     root          4096 Aug  4 05:52 _templates
-rw-r--r--    1 root     root          5129 Aug  4 05:52 conf.py
-rw-r--r--    1 root     root           437 Aug  4 05:52 index.rst
-rw-r--r--    1 root     root           805 Aug  4 05:52 make.bat

良さそうですね。
ReadTheDocs テーマと blockdiag を使うために conf.py を書き換えます。

書き換え内容は下記を参照してください。

sphinxcontrib-blockdiag の設定を見ていて思い出しましたが、 blockdiag で日本語を利用する場合日本語フォントが必要です。

IPAフォントのダウンロード

サクッと入れましょう。

mkdir /fonts
cd /fonts
wget -O ipag00303.zip http://ipafont.ipa.go.jp/old/ipafont/ipag00303.php
unzip ipag00303.zip
rm ipag00303.zip

では conf.py を書き換えます。

cd /documents
vi conf.py

変更点はざっくりと以下の通りです。

/dcuments/conf.py
# (略

# 上の方に追加
import sphinx_rtd_theme

# (略

extensions = ['sphinxcontrib.blockdiag']
blockdiag_fontpath = '/fonts/ipag00303/ipag.ttf'

# (略

html_theme = "sphinx_rtd_theme"
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]

では、適当な blockdiag を index.rtd に追加してビルドできるか試してみましょう。
追加する blockdiag は下記。
これを index.rtd 最下部に追加します。

vi index.rtd
/documents/index.rtd
.. blockdiag::

    blockdiag {
        A -> B;
    }

それではお待ちかねのビルド。

make html

どうだ!?

WARNING: dot code 'blockdiag {\n    A -> B;\n}': The _imagingft C module is not installed

あんれ〜???
謎エラー発生によりテンションが下がりましたが、気を取り直して行きましょう。
ググると freetype が無い、とか freetype を入れる前に PIL を入れた、とかそんなことが原因のようです。

https://stackoverflow.com/questions/4011705/python-the-imagingft-c-module-is-not-installed

厳密には PIL というか blockdiag が依存している Pillow のようなので、 freetype を入れて、 Pillow を入れ直します。

apk add freetype freetype-dev
pip uninstall Pillow
pip install --no-cache-dir Pillow
Installing collected packages: Pillow
  Running setup.py install for Pillow ... done
Successfully installed Pillow-4.2.1

はいOK。
再度HTMLのビルドを試します。
index.rst の変更がないまま make html するとスルーされるので、変更が無いファイルもビルドするように直接コマンドを叩きます。

/documents # sphinx-build -b html . build -a
Running Sphinx v1.6.3
loading pickled environment... done
building [mo]: all of 0 po files
building [html]: all source files
updating environment: 0 added, 0 changed, 0 removed
looking for now-outdated files... none found
preparing documents... done
writing output... [100%] index                                                                                                                         
generating indices... genindex
writing additional pages... search
copying static files... done
copying extra files... done
dumping search index in English (code: en) ... done
dumping object inventory... done
build succeeded.

やっとできましたー!バンザイ!

Dockerfile 化する

ではコンテナを落として、上記手順をDockerfile化します。

FROM python:alpine3.6

RUN apk add --update alpine-sdk zlib-dev libjpeg-turbo-dev freetype freetype-dev

# Setup sphinx
RUN pip install sphinx
RUN pip install sphinx_rtd_theme
RUN pip install sphinxcontrib-blockdiag


# Download IPA font
RUN wget -O ipag00303.zip http://ipafont.ipa.go.jp/old/ipafont/ipag00303.php
RUN unzip ipag00303.zip
RUN mkdir /fonts
RUN mv ipag00303 /fonts/ipag00303
RUN rm ipag00303.zip

# Create workspace
RUN mkdir documents

WORKDIR /documents
VOLUME /documents

CMD sphinx-build -b html source build

ビルド

$ docker build -t "suttang/sphinx-rtd" .
Sending build context to Docker daemon   2.56kB
Step 1/14 : FROM python:alpine3.6
 ---> d3265765e054
Step 2/14 : RUN apk add --update alpine-sdk zlib-dev libjpeg-turbo-dev freetype freetype-dev
 ---> Using cache
 ---> f9b74dfbe0e5
Step 3/14 : RUN pip install sphinx
 ---> Using cache
 ---> 481679fabb80
Step 4/14 : RUN pip install sphinx_rtd_theme
 ---> Using cache
 ---> f4624f1c9cd5
Step 5/14 : RUN pip install sphinxcontrib-blockdiag
 ---> Using cache
 ---> 4a8f1215942c
Step 6/14 : RUN wget -O ipag00303.zip http://ipafont.ipa.go.jp/old/ipafont/ipag00303.php
 ---> Running in 8c50a21d1d55
Connecting to ipafont.ipa.go.jp (192.218.88.244:80)
Connecting to dl.ipafont.ipa.go.jp (192.218.88.241:80)
ipag00303.zip         22% |******                         |   927k  0:00:03 ETA
ipag00303.zip         46% |**************                 |  1952k  0:00:02 ETA
ipag00303.zip         70% |*********************          |  2954k  0:00:01 ETA
ipag00303.zip         94% |*****************************  |  3968k  0:00:00 ETA
ipag00303.zip        100% |*******************************|  4194k  0:00:00 ETA

 ---> 7bbd1be59b06
Removing intermediate container 8c50a21d1d55
Step 7/14 : RUN unzip ipag00303.zip
 ---> Running in 8b9ec2261aa6
Archive:  ipag00303.zip
  inflating: ipag00303/IPA_Font_License_Agreement_v1.0.txt
  inflating: ipag00303/ipag.ttf
  inflating: ipag00303/Readme_ipag00303.txt
 ---> 9135aa18dbcd
Removing intermediate container 8b9ec2261aa6
Step 8/14 : RUN mkdir /fonts
 ---> Running in 2d655893af56
 ---> b1d088bf26d0
Removing intermediate container 2d655893af56
Step 9/14 : RUN mv ipag00303 /fonts/ipag00303
 ---> Running in 9f12be5ee89d
 ---> a6cc6b5c11eb
Removing intermediate container 9f12be5ee89d
Step 10/14 : RUN rm ipag00303.zip
 ---> Running in fa890dc377b8
 ---> 7feacda3729e
Removing intermediate container fa890dc377b8
Step 11/14 : RUN mkdir documents
 ---> Running in 9c42f44088cb
 ---> 8626b91e8118
Removing intermediate container 9c42f44088cb
Step 12/14 : WORKDIR /documents
 ---> a531d8f1ed3c
Removing intermediate container da3f03619764
Step 13/14 : VOLUME /documents
 ---> Running in 8386cf1e1598
 ---> f05dab1e7b73
Removing intermediate container 8386cf1e1598
Step 14/14 : CMD sphinx-build -b html source build
 ---> Running in 591ded5dff8a
 ---> 13c675be97fc
Removing intermediate container 591ded5dff8a
Successfully built 13c675be97fc
Successfully tagged suttang/sphinx-rtd:latest

EXCELLENT

設定初期化スクリプト

ただ、このままだと conf.py を自分で用意する必要があるので面倒ですね。
上の方で作った conf.py をイメージに保持して、 /documents/conf.py がなかったらそこにコピーする、としましょう。

まず初期化用のディレクトリを作成します。

mkdir init

conf.py をうまいことします。

cd init
vi conf.py.example

内容はこんな感じ。

https://github.com/suttang/docker-sphinx-rtd-theme/blob/master/scripts/files/conf.py

そしてこの conf.py.example をコピーするスクリプトを追加します。

vi init.sh
init/init.sh
#!/bin/sh

cp /init/conf.py.example /documents/conf.py
chmod 755 init.sh

で Dockerfile にこんな感じに追加

# Copy initialize scripts
COPY init init

そしてイメージのビルド

cd ..
docker build -t "suttang/sphinx-rtd" .

はい、では先程の初期化スクリプトが動くか確かめてみましょう。

docker run --rm -it -v $(pwd)/documents:/documents/ suttang/sphinx-rtd /init/init.sh

問題なく documents/conf.py が出来上がりましたね。
よかったよかった。

このあと色々といじって最終的な生成物はこちらになります。

https://github.com/suttang/docker-sphinx-rtd-theme

Why not register and get more from Qiita?
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away
Comments
No comments
Sign up for free and join this conversation.
If you already have a Qiita account
Why do not you register as a user and use Qiita more conveniently?
You need to log in to use this function. Qiita can be used more conveniently after logging in.
You seem to be reading articles frequently this month. Qiita can be used more conveniently after logging in.
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away
ユーザーは見つかりませんでした