ボクとSphinxとVimと。¶
ssmjp¶
#ssmjp 2011/02/22
とりあえずボク¶
なまえ：とがくし
しゅみ：インストールとか
- 最近ハマってるもの
- Sphinx, TRAC, Redmine
- Cobbler, Puppet, Capistrano, Kickstart
- Linux KVM
とりあえずボク¶
なまえ：とがくし
しゅみ：インストールとか、 ドキュメント書き
- 最近ハマってるもの
- Sphinx, TRAC, Redmine
- Cobbler, Puppet, Capistrano, Kickstart
- Linux KVM
Shpinxって？¶
- カッコイイドキュメントが作れるツール
- プレゼンだってできる
このプレゼンは¶
- Vimで書いて
- S6 (c) 2007 Cybozu Labs, Inc. 拡張を組み込んだ
- Sphinxで作成して
- ブラウザで表示しています
馴れ初め¶
行くしかねぇ！！
第一印象¶
とりあえずぐぐる
あやしい・胡散臭い・得体のしれない
公式キャラ（？）が一つ目でコワイ
「ドキュメントを作りたくなってしまう魔法のツール」なんて、もはや宗教レベル
- とにかく俺はドキュメントを書くのが大キライ
- めんどくさがり屋
- 日本語が下手
- 説明が下手
勉強会に行ってきました¶
2010/12/03 jus勉強会
- 「ドキュメント作りが楽しくなると、ソフトウェア開発や運用はきっともっとずっと 楽しく なります。 」
- この文章にはシビれた
知らないことばかり
ソースコードにテストがあってドキュメントがある
- Pythonとか(Javaも？)フツーだよねーとか思ってた
- ゲゲェー！！そこからhtmlやらTeXに出来るのか！
disってゴメン///¶
- ナニコレ カッコイイ
- ドキュメントが書きたくなる魔法にかかりました
- 使い方を調べているうちに「次は何をドキュメントにしようか」という気持ちに
- 書いてて面白い
とにかく成果物が カッコイイ
個人的にツボだったところ¶
- 元のドキュメントがプレーンテキスト
- Officeキライ
- というか、物理的なWindowsマシンを持ってないので扱えない
メモはいつもプレーンテキスト
- 変換にmakeを使っている
- make大好き小僧
htmlに変換できる
カッコイイ
他のツールと比較してみる¶
- wiki
- word
- えくせ。。
excel¶
- いいところ
- 編集画面がそのままアウトプット画面になる
- 何も考えなくてもアウトプットがイメージできる
- わるいところ
- 見た目通りに印刷できない
- 再利用しにくい
- 後のことを考えてない
そもそもドキュメントを書くツールじゃなくね？
dummy¶
あくまで個人的な見解ですのであしからず
使ってみる¶
- とりあえず、過去のメモをreSTに
- たまたまファイル名を日付にしていた
- toctreeに並べるだけで時系列順に並んだ
自分が何を書いたか思い出した
ブラウザで気軽に見れるのでよく見直すようになった
使ってみよう¶
- インストール
- Pythonが入ってる環境なら3分
% sudo easy_install sphinx
使ってみよう¶
easy_install が許されるのは小学生までだよねヒャッハー！！
% sudo pip install sphinx
使ってみよう¶
ドキュメントを格納したいディレクトリを作って
% sphinx-quickstart
- いくつかの質問に答えるだけ
- 必須項目以外は基本エンター連打OK
- Project name:
- Author name(s):
- Project version:
後で変更も出来る
reStructuredText事始め¶
Sphinxのサンプル
=================
Sphinxとは何か？
-----------------
* ドキュメント生成のツール
* reStructuredText記法(Wikiっぽい?
* ページ間のリンクを自動生成
* 強力なコードハイライト
* HTML, PDF, ePub, htmlhelp, latex, man...
セクション¶
- 見出しを記号で囲む
- 下だけ or 上下
- 使用する文字や順番に決まりはない
- 使われていない種類が出てくると自動的にレベルが変わる
ディレクティブ¶
汎用の明示的マークアップ
reSTの拡張のためのメカニズムの一つ
.. function:: xxxx
ドット2つ、スペース、ディレクティブの名前、コロン2つ、引数
インデントが同じレベルになる次の段落までが１つのブロックとして扱われる
toctree(ディレクティブ)¶
- 作ったドキュメントを並べる(目次みたいなもの)
- toctreeに載らないドキュメントは警告される
- 見出し(セクション)を自動的に解析してくれる
- いちいち書くのがめんどくさかったらglobを使うとワイルドカードで指定できる
- maxdepthで見出しを付ける深さを指定
コードハイライト(ディレクティブ)¶
- code-block
- 今まで散々見てますね
- 200種類以上の言語に対応してるらしい
- bash
- Python, Ruby, Perl, PHP ...
コメント¶
.. から始まる行でディレクティブじゃないものはコメント
ブロックが丸ごとコメントになるにので複数行のコメントがラク
.. このインデントされたブロック 全体がコメントです この行もまだコメントです
テーブル¶
コレは意外とメンドクサイ
シンプルテーブル
===== ===== ======= A B A and B ===== ===== ======= False False False True False False False True False True True True ===== ===== =======
テーブル¶
コレは意外とメンドクサイ
グリッドテーブル
+------------------------+------------+----------+----------+ | Header row, column 1 | Header 2 | Header 3 | Header 4 | | (header rows optional) | | | | +========================+============+==========+==========+ | body row 1, column 1 | column 2 | column 3 | column 4 | +------------------------+------------+----------+----------+ | body row 2 | ... | ... | | +------------------------+------------+----------+----------+
編集する為のオススメエディタ¶
基本的に文字が打てればなんでもいい
- 出来たら便利なこと
- マクロ機能が使える
- 複数行のインデントがまとめて編集できる
- 個人的にはvimオススメ
- reSTのシンタックスハイライトがある
MySQLの出力をグリッドテーブルに変換する¶
vimscript
vip:<ESC>'<jjY:s/-/=/g<CR> :for i in range(line("'<")+3,line("'>")-2)\| exec 'norm jp'\|endfor<CR>
- ヴィジュアルモードに移行(v)
- 段落を選択(ip)、編集モードに移行(:)、キャンセル(<ESC>)
- 先頭に移動(‘<)し2行下にカーソルを移す(jj)
- ヤンク(Y)してから-を=に変換(:s/-/=/g<CR>)
- カーソルを下に移動してペースト(norm jp)
- 最終行まで繰り返す(for〜endfor)
こんな使い方¶
with Dropbox
- with Subversion
- hook script との連携
with Dropbox¶
Sphinx-Users.jpのサイトにも例が載ってますね
- Dropboxのフォルダの中でsphinx-quickstartをやる
- 複数端末のドキュメントが同期できて(ﾟДﾟ)ｳﾏｰ
with Subversion¶
working copyの中でsphinx-quickstartをやる
- hook script との連携
post-commitを使用
サーバ内のworking copyへcheck out
working copy内のドキュメントをビルドする
- 再度commit(post-commitが走らないような仕掛けを入れる)
- _buildがworking copy内にあるので最新にしておかないとconflictを起こす
クライアントでcheck out(ビルド済みのドキュメントが手に入る)
with Subversion¶
with Subversion¶
- メリット
- 手元にビルド環境がなくてもビルド出来る
- デメリット
- しょっちゅう_build内でconflictが起こる
- make cleanで毎回消してる
- check outで毎回_build全体が更新される
ハマリポイント¶
インデント重要！！
Linux環境だと大文字小文字を区別する！
- 日本語のファイル名
- ビルドの通らないダメ文字があるっぽい
- そもそもtoctreeに日本語が指定できない
俺、「togakushi’s Documentation」って書きたかったんだ…
man_pages = [ ('index', 'togakushi', u'togakushi's Documentation', [u'togakushi'], 1) ]conf.pyで構文エラー発生
運用現場で使ってみたい！！¶
ところで！！
運用現場で使ってみたい！！¶
現場で使ってみたくなったよ！！
運用現場で使ってみたい！！¶
- エクセル手順書からの脱却
- 一度使ったらそれっきり(が多い)
- 再利用しにくい
- 作業する人しか作らない/見ないのでノウハウが展開されない
- GUI操作の手順書なのに画像がなかったりする
- 繰り返し同じ操作画面を作るのが手間
壁¶
- reSTを覚えること
- エクセルと違ってアウトプットのイメージが必要
ビルド環境
公開場所
- 印刷どーする？必要なの？
- レビューは生reSTを印刷？
- おエライさんは怒りそう
- プロジェクタに写せばいいかな
- とりあえずテメーの為に作ってんじゃねぇから
何が嬉しいか¶
- フォーマット考えなくていい
- 手軽に手順書のモジュール化ができる
- replaceを使ってサーバ名を入れ替えたり
お し ま い¶
おまけ¶
- blockdiag
- 遷移図生成ツール
- seqdiag
- シーケンス図生成ツール