Download to read offline
More Related Content
Sphinxの環境構築が再現できない問題をDockerで解決してみた
- 1.
- 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 forWindowsで、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.