Sphinx + Jenkins で始めるドキュメントの継続的インテグレーション に感化されて。
ホイホイと brew でインストールして。。。 はいけない。
これは別のSphinx。
|
1 2 3 4 |
$ $ brew install sphinx # これはダメ $ |
たいていの作業が一人プロジェクトとは言え、
コードの量がある程度大きくなって来たら、
記憶はあてにならない。
なので、ドキュメント化は必須。
出来れば作業を軽くしたいし、自動化もしたい。
これまでは org-mode から記事を抜き出して流用していたけど、
org-mode では TODOとメモ的な運用をしているし、
emacsがないと変換できないので、人にあげられない。
人にあげる時には、 org-mode から htmlやpdfに変換していたけど、 この作業が結構煩雑なので、思った通りの綺麗な文章に変換するのは
ちょっと手間だし、ついつい拘って時間をかけてしまう。
人に編集や更新してもらうことも難しい。
本当のTODOとドキュメントが混ざるのも管理しにくいので、
残す資料は、巷で流行りの Sphinx を試してみることにする。
早速、インストール。
ここで要注意。
冒頭の通りbrewに同じ名前の別のアプリがあるので、pipを使うこと。
|
1 2 3 4 |
$ $ pip install Sphinx $ |
で、インストールが済んだら、最初のドキュメント作り。
sphinx-quickstart でも雛形を作れるけど
ある程度ドキュメントを作ったことがある人なら、
2portfolio.zipのサンプルを複製する方が分り易いと思う。
他のツールでドキュメントを作ったことがある人なら、
チュートリアルで一つ一つ覚えていくより、
凡そのコマンドとドキュメントの構造が理解し易いはず。
今回の一番のおたのしみはブロック図。
org-modeでは、graphvizとplantUMLを使っていたけど、 やや癖があったり、日本語が不自由だったりするので、 もうちょいお手軽なブロック図作成スクリプトが欲しかった。
Sphinxでは、blockdiagが良く使われている様なので試してみる。
|
1 2 3 4 5 6 7 |
$ $ pip install blockdiag sphinxcontrib-blockdiag $ pip install seqdiag sphinxcontrib-seqdiag $ pip install actdiag sphinxcontrib-actdiag $ pip install nwdiag sphinxcontrib-nwdiag $ |
インストールしたのは、以下の作画ツール。
- ブロック図生成ツール blockdiag
- シーケンス図生成ツール seqdiag
- アクティビティ図生成ツール actdiag
- ネットワーク図生成ツール nwdiag
残念ながら、クラス図などにピッタリと都合が良いものは無さそう。
書式はgraphvizとほぼ同じで、テキスト状態でも内容が見易い。
さっくり日本語が出し、色や背景、各ブロックの説明一覧が簡単に追加できるなど、
とても気が効いている。