Sphinx 再度再び

失われたブログに、間違いなく書いていたと覚えているのがSphinxのことで、これはソニー時代に若くて優秀なエンジニアのチームがドキュメント作成に使っていたのを見て、僕も使いたいと思いつつ、なかなかとっつきにくくてそのままになっていたものでした。

転職に伴い、ドキュメントを効率的に管理する必要性が出てきたので、使ってみることにしたのですが、当時SphinxからPDFを出力するには2通りの方法があって、そのひとつのLaTexを使う方がうまくいかなかったため、rst2pdfを使う方にしました。ただこれ、いろいろ不具合があって、それを回避しながら、騙し騙し使っていたのですが、ユーザーグループに相談したところ、rst2pdfはメンテされていないのでLaTeXを使う方が良いとのことでした。

その後、「Sphinxをはじめよう 第2版」が発売され（今確認したら第3版も出たようです）、情報が充実されたり（当時、ググると古い情報が多かったのですが、今ググってみると、当時よりも情報も充実したようですし・・・）、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作成までいきます。