« 買いました報告:Android アプリ設計パターン入門 | トップページ | ぼくのかんがえたさいきょうのドキュメントCIかんきょう »

2018年7月20日 (金)

Sphinxの環境を整える

この記事の目標

  • Sphinxの編集環境を作る
  • こぎれいなPDFを出力できる環境をWindowsで作る

Sphinx is 何


SphinxはPythonで書かれたドキュメントビルダで、reStructuredTextというマークアップ言語で書かれたソースをこぎれいなHTMLなんかに変換してくれる優れもの。

Sphinxのインストール


詳しくは公式のSphinxのインストール参照。

以下、かいつまんで書く。

  1. Pythonをインストール、デフォルトでよいが、公式ではPython 3.xを推奨している模様
  2. PIPをインストール
  3. pip install -U Sphinxを実行


編集には、Visual Studio CodeとreStructuredText拡張を使っているが、UTF-8が扱えれば使い慣れたエディタで大丈夫。

こぎれいなPDFをWindowsで作る


実はここがこの記事のメイン。


とりあえず、自分で試したWindowsとLinux(Ubuntu)で必要だったパッケージについて、ざっくりまとめた。

ビルダ html epub latex latexpdf
Windows
要TeX Live

要TeX Live, GNU Make, sh
Linux
要TeX Live

要TeX Live


この表のとおり、SphinxでこぎれいなPDFを作るにはTeXの力を借りる必要があるんだが、これにはTeX Liveというパッケージを使うのが一番簡単だ。


インストーラはInstalling TeX Live over the Internetで取得できる。

Windowsの場合、ネットインストール型のインストーラを使うのがお手軽だが、時間はとてもかかる(2時間くらい?)ことを覚悟したほうがいい。

とはいえ、待っているだけで基本終了するので、特に難しいところはないはず。


また、Sphinxのlatexpdfビルダは、WindowsのDOS窓では処理ができない動きをするので、UNIX由来のツールであるGNU Makeとshを入れておく必要がある。

これにはMSYS2を使うことにした。


QiitaにMSYS2 による gcc 開発環境の構築という記事を投稿している方がいるので、そちらを参考にmakeだけを入れる。

入れたら、C:\msys64\usr\binをパスに追加しておくこと。


ここまでできれば、Sphinxのドキュメントプロジェクトのあるディレクトリでmake.exe latexpdfとやればこぎれいなPDFが出力できていることだろう。


なお、「Sphinxのlatexpdfビルダは、WindowsのDOS窓では処理ができない動きをする」件、一応Issueにも挙がっているようで、日本のメーリングリストでも話題になっているんだけど、なかなかfixしないよなぁ....。


|

« 買いました報告:Android アプリ設計パターン入門 | トップページ | ぼくのかんがえたさいきょうのドキュメントCIかんきょう »

コメント

コメントを書く



(ウェブ上には掲載しません)




トラックバック


この記事へのトラックバック一覧です: Sphinxの環境を整える:

« 買いました報告:Android アプリ設計パターン入門 | トップページ | ぼくのかんがえたさいきょうのドキュメントCIかんきょう »