sphinxとblockdiagのインストール

mac 設定 python

ドキュメント作成めんどいなーとおもいながらネットをぶらぶらしてたらSphinx + blockdiag で始めるドキュメント生活 @ yokohama.pm 2011/05 - TIM Labsとか見つけた。いままで文章とかTexで書いてたけど、ちょっとした内容の物を書くとか図が増えてくると大変だったのでsphinxはどうかなーと思いながら入れてみる。あと、拡張機能のblockdiagとかかっこよすぎ。自動でブロック図とか作ってくれるあたり惚れる。

sphinx

インストールは簡単。easy_installでsphinxをインストールするだけ。easy_install入ってない人はpythonから入れよう。

> sudo easy_install sphinx

入れたら確認のために一度起動してみる。

> sphinx-quickstart
Welcome to the Sphinx 1.1 quickstart utility.

Please enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).

Enter the root path for documentation.
> Root path for the documentation [.]:

起動を確認。Ctrl+Cで終了させる。

blockdiag

blockdiagのサイト（sphinxcontrib-blockdiag — blockdiag 1.0 ドキュメント）を参考にインストール。
こちらもeasy_installで簡単。

> sudo easy_install sphinxcontrib-blockdiag

試しにドキュメントを作ってみる

> sphinx-quickstart

sphinx-quickstartで聞かれる項目についてはsphinx-quickstartの詳細説明 — Python製ドキュメンテーションビルダー、Sphinxの日本ユーザ会を参考に。
プロジェクト作ったら具体的に中身を書いていこう。テストなんで簡単なかんじで。

まずはsphinxプロジェクトの設定。conf.pyの内容を変更。
extensionsにblockdiagを追加して、更にフォントを指定する。けっこう適当。フォントの指定しないとエラー吐くので注意。

> vim conf.py
...
# Add any Sphinx extension module names here, as strings. They can be extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = ['sphinxcontrib.blockdiag']
blockdiag_fontpath = '/Library/Fonts/Osaka.ttf'

設定が終わったら具体的に内容を書いていく。新たにtest.rstというファイル作ってドキュメントを作成。

> vim test.rst

テストのテスト
=============================
:日付: 2011/11/01

概要
===================
sphinxとblockdiagがちゃんと動くかのテスト。

blockdiagのテスト
===================
明日から昨日への輪廻

.. blockdiag::

  diagram {
    一昨日 -> 昨日 -> 今日 -> 明日 -> 明後日;
    明日 -> 昨日
  }

index.rstにtest.rstを追加。

> vim index.rst

...
Welcome to Sphinx-test's documentation!
=======================================

Contents:

.. toctree::
   :maxdepth: 2

   test

書くときに拡張子.rstは書かない。ここまでできたら後はmakeコマンド打つだけ。"make html"でHTMLファイルを、"make latex"でTex形式のファイルを作ってくれる。

> make html

そして出来たHTMLファイルの一部がこんな感じ。ブロック図とか結構スマートにかけて嬉しいね。編集も楽だしrstファイルそのままでもある程度読めるのでちょっとしたドキュメントとして扱うことも出来るね。

まとめ

ちょっとした編集が多いドキュメントにはありがたい。テキストで編集できるので軽いし簡単だし、体裁を勝手に整えてくれるので文章を書くのに集中できる。今後しばらく使って様子見ます。とりあえずブロック図をテキストで書けるのは便利やー。