AWS / PHP / Python ちょいメモ

amazon web service , PHP, Python を使ったときのメモ。日本語でググってもわからなかった事を中心に。

WindowsでSphinx+blockdiag環境を整える (Sphinx standalone installer利用)

sphinx ドキュメント

AWS SDKを始め、多くのPHPプロジェクトのドキュメントに使われてるSphinx。

Windowsで一番手軽そうな環境構築方法を、メモしておきます。

Sphinxは簡単に構築できたものの、blockdiagの使い方（始め方）がわからず相当悩みました。読むべき場所を知ってしまえば大した事ないのですが。。。Sphinx使ってドキュメント書こうと思ってる人なら、結構な確率で喜べるツールと思いますので、是非合わせて。

大まかな流れ

次のような順番で作業をしました。今回のOS環境は、Windows7 SP1(x64)。Standalone installer は、日本のSphinx-Users.jpの方々が提供してるパッケージ。便利です。

  1. Sphinx
    • Sphinx standalone installer をインストール
    • パスを確認
    • 使ってみる
  2. blockdiag
    • conf.pyに記述をいれる
    • blockdiagで書く

Sphinx環境を準備する

インストールに成功すれば、後は設定だけでいけます。Uninstallerも付いてるので、気軽に試していいかと。

Sphinx standalone installer

Sphinx-Users.jpが配布してるパッケージを利用して、Python + Sphinx + blockdiag等を一発でインストールします。

管理者権限で実行すると、Win7SP1の場合 "C:\Program Files (x86)\Sphinx" にインストールされました（32bit版のみの提供）。

パスの確認

インストーラーがパスも設定してくれてるはずですが、念のために確認。コマンドプロンプト(cmd.exe)を起動して、次のいずれかで確認できます。

  • whereコマンドを使う:Vista以降
    • where python
    • where sphinx-quickstart.exe
      • いずれも同じ ~\Sphinx\ フォルダ配下が帰ってくればOKと思う
  • 環境変数 PATH の中身を見る
    • path
      • 出力された内容の中で、次の2つがあるかを確認
      • C:\Program Files (x86)\Sphinx\python
      • C:\Program Files (x86)\Sphinx\bin

Python単体インストールとかをしてると、チグハグになってる可能性もあるので、その場合にはPATHの指定順番などを替えるなどの調整をして対処しましょう。

使ってみる

あとは、Sphinx-Users.jpが提供してくれてる手順などを参考に使ってみましょう。

blockdiagを使う

ブロック図を生成してくれる、Sphinx拡張を使います。前述のインストーラーを使っていれば、すでにインストールは完了している状態です。

conf.pyに記述をいれる

sphinx-quickstart.exe などにより作成したフォルダにある conf.py に、blockdiagをプロジェクトで使うように宣言をします。

  • extensions に sphinxcontrib.blockdiag を設定
    • 例）extensions = ['sphinxcontrib.blockdiag']
    • extensionsの行はすでにあると思うので、他が書かれていれば sphinxcontrib.blockdiagを追加
  • blockdiag_fontpath 行を追加して、TrueTypeフォントを指定
    • 例）MSゴシックを使う場合（MSP？）
    • blockdiag_fontpath = 'c:/windows/fonts/msgothic.ttc'
    • TrueTypeは、blockdiagで日本語を使ったときに必要となるとのこと


上記についての説明は、公式ドキュメントに詳しいです。

blockdiagで書く

あとはSphinxのrstドキュメントに、blockdiagを使った図を記述して make htmlすればOK。

デフォルトはPNG画像を生成して、埋め込んでくれます。

記述例）

.. blockdiag::

   blockdiag {
      A -> B -> C;
   }
intaractive shell

blockdiagを記述して、makeするのが大変な場合は、ここで荒い図を完成させておくといいかも。

その他

Sphinxを手に入れると、Word/Excelなどから離れて、ドキュメントもバージョン管理に入れやすいというのが気持ちがいいです。

Sphinxスタンドアロン インストーラーを使うと blockdiag.exe （独立アプリ版）?も入ると思い込み、そこが動かずに難儀してたのですがパッケージ自体がSphinxに特化してるわけですし、入らないよなぁと気づくのにも時間がかかった。


途中blockdiagの動作をさせる方法がわからず、個別インストールも試みたのですが、blockdiagの依存パッケージPIL(Pillow)に必要なモジュールを入れるあたりで挫折。。。普段使わない言語の環境を構築するのは、なかなか大変なものですね。

blockdiagが動いたときは、うれしくて思わず4つも図を作ってしまいました。DOT言語？っていいですね。