失われたブログに、間違いなく書いていたと覚えているのがSphinxのことで、これはソニー時代に若くて優秀なエンジニアのチームがドキュメント作成に使っていたのを見て、僕も使いたいと思いつつ、なかなかとっつきにくくてそのままになっていたものでした。
転職に伴い、ドキュメントを効率的に管理する必要性が出てきたので、使ってみることにしたのですが、当時SphinxからPDFを出力するには2通りの方法があって、そのひとつのLaTexを使う方がうまくいかなかったため、rst2pdfを使う方にしました。ただこれ、いろいろ不具合があって、それを回避しながら、騙し騙し使っていたのですが、ユーザーグループに相談したところ、rst2pdfはメンテされていないのでLaTeXを使う方が良いとのことでした。
その後、「Sphinxをはじめよう 第2版」が発売され、情報が充実されたり(当時、ググると古い情報が多かったのですが、今ググってみると、当時よりも情報も充実したようですし・・・)、Sphinxもバージョンアップされ、いろいろと環境が整ってきたので、今はLaTeXを使う方法でドキュメントを書いています。
ただ、Sphixドキュメントを書くのに(もともとPythonのドキュメント作成ツールだったので)、エディター/環境としてPyCharmを使うと便利なのですが、rst2pdfだとSphinx DocumentのターゲットにPDFが出てきたのだけど、LaTeX経由では出てこず、どうしてもコマンドラインでmakeを叩く必要があるのが不便でした。
そのあたりで悩んでいるところに「Pythonからバッチファイルを起動、変数を渡す」という記事を見つけたので、それを参考にmake.pyを作って、それをPyCharmから呼び出すことで、無事全部PyCharm内で閉じてSphinxドキュメントからPDFを作るところまでできるようになりました。
make.pyは、以下のように作成して、Sphinxドキュメントのルートに置きます。
import os import sys cmd_file = "make.bat" # .cmdファイルへのパス argvs = sys.argv # 複数の引数を持つ場合 argc = len(argvs) command = cmd_file for i in range(1, argc): command += " " + argvs[i] os.system(command)
あとはPyCharmの中から”Create New Project”を選び・・・
以下のようにSphinxドキュメント用の(Python)プロジェクトを作成します。 プロジェクトができたら、PyCharmの中から”Tools”メニューの”Sphinx Quickstart”を選ぶことで、Sphinxのテンプレートが作成できます。 後は、順に必要な情報を入れていきます。次に「ボタン一発」でPDFを作成するため、”Run”メニューの”Edit Configurations”を選択します。
普通は以下のように”Python docs”の下の”Sphinx task”を選ぶのですが・・・ここでは”Python”を選びます。
そして、以下のように起動するスクリプトとしてmake.pyを選び、与えるパラメーターに”latexpdf”を選べば、make.pyがmake.batを呼び出してくれて、”latexpdf”を渡してくれるので、PDFが作成できるというわけです。 あとは、右上の”Run”ボタンを押すだけで、一気にPDF作成までいきます。