タグ別アーカイブ: blockdiag

Sphinxで始める極楽ドキュメント作り

Sphinx + Jenkins で始めるドキュメントの継続的インテグレーション に感化されて。

ホイホイと brew でインストールして。。。 はいけない。
これは別のSphinx。

たいていの作業が一人プロジェクトとは言え、
コードの量がある程度大きくなって来たら、
記憶はあてにならない。

なので、ドキュメント化は必須。
出来れば作業を軽くしたいし、自動化もしたい。

これまでは org-mode から記事を抜き出して流用していたけど、
org-mode では TODOとメモ的な運用をしているし、
emacsがないと変換できないので、人にあげられない。

人にあげる時には、 org-mode から htmlやpdfに変換していたけど、 この作業が結構煩雑なので、思った通りの綺麗な文章に変換するのは
ちょっと手間だし、ついつい拘って時間をかけてしまう。
人に編集や更新してもらうことも難しい。

本当のTODOとドキュメントが混ざるのも管理しにくいので、
残す資料は、巷で流行りの Sphinx を試してみることにする。

早速、インストール。

ここで要注意。
冒頭の通りbrewに同じ名前の別のアプリがあるので、pipを使うこと。

で、インストールが済んだら、最初のドキュメント作り。

sphinx-quickstart でも雛形を作れるけど
ある程度ドキュメントを作ったことがある人なら、
2portfolio.zipのサンプルを複製する方が分り易いと思う。

他のツールでドキュメントを作ったことがある人なら、
チュートリアルで一つ一つ覚えていくより、
凡そのコマンドとドキュメントの構造が理解し易いはず。

今回の一番のおたのしみはブロック図。

org-modeでは、graphvizとplantUMLを使っていたけど、 やや癖があったり、日本語が不自由だったりするので、 もうちょいお手軽なブロック図作成スクリプトが欲しかった。

Sphinxでは、blockdiagが良く使われている様なので試してみる。

インストールしたのは、以下の作画ツール。

  • ブロック図生成ツール blockdiag
  • シーケンス図生成ツール seqdiag
  • アクティビティ図生成ツール actdiag
  • ネットワーク図生成ツール nwdiag

残念ながら、クラス図などにピッタリと都合が良いものは無さそう。

書式はgraphvizとほぼ同じで、テキスト状態でも内容が見易い。

さっくり日本語が出し、色や背景、各ブロックの説明一覧が簡単に追加できるなど、
とても気が効いている。