勉強会で発表した資料。 https://sciencepark.connpass.com/event/128462/

1. Sphinxの環境構築が再現できない問題をDockerで解決してみた
サイエンスパーク株式会社 須藤圭太

2. • ID：suusanex（ connpass・Twitter・GitHub共通）
• 名前：須藤圭太
• サイエンスパーク株式会社という独立系ソフトウェアベンダーに所属
• 4年ほど受託開発で、上流から下流まで全部を回す
• ここ6年ほどは、自社製品開発を担当
勉強会、今後も開いていきます。
https://sciencepark.connpass.com/
自己紹介
2

3. • Sphinx＋PlantUMLで、UML図入りの仕様書がテキストで書ける（簡単に紹介します）
• とても便利なので、皆で使おう！
• ところが・・・
• 環境構築で結構躓くので、対策を考えてみました
概要

4. • 簡単な例を見せます
• Markdownテキストで文書が書け、書式は後から付けられる
• テキストでUMLの図が書ける
• ↓
• テキストと図のすべてが、gitでマージ・差分確認可能に！
• 素のSphinxだとそこまではできないので、conf.pyに次の拡張を追加
• Markdownのパーサーとして、Markdown Preview Enhancedを使用（pandoc変換の実装らし
い）
• PlantUMLを追加
Sphinxの簡単な紹介

5. • Pythonなので、なんとなく手順に従っても構築が上手く行かない場合がある
• ライブラリ間のバージョン違いなどによる相性
• Windows環境によるエラー
• 例えば
• UnicodeDecodeError: 'utf-8‘
• →pipのバグで、Windowsユーザー名に日本語があるとダメだった
• ModuleNotFoundError: No module named 'markupsafe._compat‘
• →MarkupSafeを再インストールすると解決 謎
構築の問題

6. • pyenvで環境を作っておく
• →フルパスなどに依存するので、他の環境へは渡せない
• pip freezeや単純な手順書などで、ライブラリとバージョンまで固定して再現可能にす
る
• →他の環境でも上手く行った、が・・・
• 「PlantUMLをインストールして環境変数を設定」などのPythonの外の設定でミス発生
• Python以外の環境もまとめて統一できる方法が欲しい
案1：Python環境の複製

7. • Docker for Windowsで、Dockerfileを作って環境統一
• 上手く行った
• 直接Windows上で実行するよりも時間がかかるが、構築ミスがない
• バッチファイルを用意することで、コンテナを使い慣れない人でも手軽に使える
案2：Dockerコンテナ

8. • Dockerfileを見せます。概要は次のような感じ
• sphinxと必要ライブラリ（sphinxcontrib_plantumlなど）をインストール
• PlantUMLをDLして、環境変数設定
• pandocをDLしてインストール
• さらにコンテナを使い慣れない人用のバッチファイルを用意
• コンテナを起動してカレントフォルダの中身をコンテナ内にコピー
• bashでSphinxコマンド受付
• exitしたら_buildフォルダをコンテナからカレントフォルダへコピー

9. • 構築の問題があって社内でいまいち広まらなかったSphinxだが、これでいける
• 便利なので構築で挫折せずにみんな使ってみてほしい
• 今後はこの辺りをやりたい
• Azure Pipelinesでコンテナを使い、ドキュメントのCI＆他のPCのマシンパワーを利用
• conf.pyの書き換えも手間なので、テンプレート化
まとめ

10. SP1906-E10-01