« 買いました報告: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かんきょう »

コメント

コメントを書く



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




トラックバック

この記事のトラックバックURL:
http://app.cocolog-nifty.com/t/trackback/164672/66962263

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

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