Sphinx 再度再び

失われたブログに、間違いなく書いていたと覚えているのが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”を選び・・・

Create New Project

以下のようにSphinxドキュメント用の(Python)プロジェクトを作成します。

プロジェクト作成

プロジェクトができたら、PyCharmの中から”Tools”メニューの”Sphinx Quickstart”を選ぶことで、Sphinxのテンプレートが作成できます。

Sphinxテンプレート作成

後は、順に必要な情報を入れていきます。

次に「ボタン一発」でPDFを作成するため、”Run”メニューの”Edit Configurations”を選択します。

run configurationを作成

普通は以下のように”Python docs”の下の”Sphinx task”を選ぶのですが・・・

ここでは”Python”を選びます。

Pythonのプロジェクトとしてmake.pyを起動するわけです

そして、以下のように起動するスクリプトとしてmake.pyを選び、与えるパラメーターに”latexpdf”を選べば、make.pyがmake.batを呼び出してくれて、”latexpdf”を渡してくれるので、PDFが作成できるというわけです。

make.pyを起動する設定

あとは、右上の”Run”ボタンを押すだけで、一気にPDF作成までいきます。

これで完成!

カテゴリー: コンピューター, 仕事 パーマリンク

1 Response to Sphinx 再度再び

  1. Kimi のコメント:

    ちなみに、この方法でPDFを作った場合、自動的に表紙に「ビルド日」が入ってしまうので、同じソースでビルドしても、ビルドした日によってドキュメントが(日付が違うだけで)変わってしまいじます。
    これを避ける方法を探していたのですが(ちなみにrst2pdfの時も同様に苦労してcover pageの設定でなんとかした)、結構見つからず・・・

    https://qiita.com/kazetof/items/d410dae312d56b7324c0

    こんな感じの書き込みで「無理でした」とか・・・ orz

    でもって、これまたユーザーグループに聞いたところ、なんとconf.pyの中にtoday=’ ‘と、todayを空白(スペース)に設定しておくだけで回避できることを教えてもらいました!(「空文字」”にするとtodayが設定されていないことになって、結局ビルド日が出てしまうので「スペース」’ ‘にすることがキモです)

コメントを残す

メールアドレスが公開されることはありません。 * が付いている欄は必須項目です

CAPTCHA