.. _2011-05-30-restudy-mini-meeting-0: **************************************************************** 2011-05-30 reSTudy mini meeting #0 **************************************************************** 場所 ビープラウド 参加者 * tk0miya * shimizukawa * tcsh * shkumagai * (AE35, altnight) * r_rudi ================================================================ まとめ/TODO ================================================================ * ディレクティブのサンプル一覧作る * tk0miyaさんが最初のバージョンを作ってくださいました * literalincludeで楽々 * 「初めてのSphinx」を書く * 本文 * headings * list * table * hyperlink (外部リンク) * 次の段階 * 画像 * 内部リンク * テーマをカスタマイズするコツを解説する * チートシートを作る * sphinx逆引き集を作る * sphinxの1clickインストーラを作る(shimizukawa) * quoteが変わって困る場合はhtml_use_smartypantsをFalseに * includeを頻繁に使いたいが、headingの衝突が起きる。回避したいな ================================================================ 議論 ================================================================ ---------------------------------------------------------------- ディレクティブの例が欲しい ---------------------------------------------------------------- * tableはcsv-table * 知らなかったので数時間苦労した * sphinxチュートリアルは翻訳？ * 自作 * sphinx.jpではディレクティブの説明が文言だけ * サンプルをきっちり書いてあるといいかも * 特にcsv-table! * あとはnoteやwarning * defaultのテーマはtodoがいけてない * 運用用css * テンプレート改造手法を広める * 内容はチュートリアルにほとんど入っているんだけど、章立てがよくない * ディレクティブの説明が分散してたり * 初心者には重い * reSTのquickstartはいけてる * sphinx-usersは開発者にはいいが、運用さんにはつらい * チートシートが欲しい * どう見えるドキュメントが欲しいのか、逆引きが欲しい * よく使うディレクティブ (togakushi) * index * tree構造で三つまで書けるし * 日本語対応extentionを書いている人がいる * contents * glossary * only * 式でincludeしたりしなかったりできる * リリース用と作業用とか * プロジェクトの分割の単位を悩んでいる * intersphinxという仕組みがある * todo使えるよね * ドキュメント書かなきゃ、でもあとで、と言うときに使ったり * todo-listで一覧表示できる * conf.pyでtodoを出さないとかもできる * sphinxのreadmeからdirecitive一覧を抽出してみた * 結構いっぱい * これを読んでいくのもおもしろそう * ドメインは基本的に言語ごとだから外してもいい * rst:directive == directiveの説明を書くためのdomain * role * guilabelとかmenuselectionとか使えるかも * replaceをliteralincludeすると “” が変わる? * 張り付けたときにエラーになる * エスケープしたいができる？ * literarlincludeは展開されない * ていうか、別にincludeじゃなくても変換される * make textだと変換されないのでhtml rendererの問題か * バグともいいきれない… * html_use_smartypants をconf.pyでFalseにする！ ================================================================ includeの使い方 ================================================================ * includeを頻繁に使いたいが、headingの衝突が起きる * 意図せず子になったり * 相対的な関係がおかしくなったり * 子に入れる専用のincludeディレクティブが欲しいかも * headingだけ書いてあるrstをincludeしてる * headingsの衝突を回避できるとうれしい * 定義用のファイルは別にあるけどその拡張子はなんだろう * 今は.def * ディレクトリに分けるのはありだけど、defとpartsと、とか * includeの使い方 * プログラム中にドキュメントを埋め込んである場合に使ったり * このために”../../”とかが許されてるのかも * ただ、使いまわしの頻度が運用屋さんは多い * 一つのファイルから複数のファイルに分ける時 * 運用屋さんはスクロールしても3画面分ぐらい * 翻訳した時は章ごと * 今書いてるのは節まで分けて一個のファイルに分けている * 意味ブロックで一つのファイルになるので結構良い ================================================================ 自動化 ================================================================ * 日付を入れておく理由 * Version管理を使える人ばかりとは限らない * その日の作業をしたらハンコ押して取っておく、と言う感じ * Makefileに * jenkinsでいいんじゃないかなぁ。 * buildサーバとドキュメントサーバを同じにする * buildすればどっかで公開してくれるし * hgをpollingして結果をメールしてくれたり * jenkinsは簡単にインストールできる？ * javaだとfreebsdだといろいろめんどいかも * jenkinsは個人用では使えないか * 基本的に中央サーバで使うもの * quick-startをもっと賢く * iniファイルにできないかと考えている(shimizukawa) * iniファイルはなんかのコマンドでepub追加とかすると追加していく * conf.pyを自動生成してほしいな * ~/.sphinxみたいなのを作っておいて読んだり * どこまで共通化/一般化できるのか * conf.pyは相対パスで書けるので一つ上に置いてある (togakushi) * conf.pyとconf.local.pyがあって、localはドキュメントに依存とか * themecoreとかでテーマも入れられたらいいな ================================================================ ドキュメントの例が欲しい ================================================================ * 運用ドキュメントをダミーにして見せてほしい * 本当にincludeなのか * includeしながら入れ替えたい * partsの組み合わせでドキュメントができるので。 * スナップショットを取って、一行書いてを繰り替えして、最後にコマンド叩くとrstができるといいな * pipeでsphinxに渡してparseしてくれるとうれしいかも * バッチ処理でドキュメント生成が楽になるのでは * sphinxは1ファイルで完結しないのでいろいろ前提置く必要あるかも * rstとJSON/YAMLとの一方向のparseが出きるといいかな * rst2pdfとか1ファイルを変換してた。でも構造化してないと辛いのでsphinxができた * docutilはファイル1つを対象としている ================================================================ blockdiag話 ================================================================ * 画像に「1番」って書きたいってOSCで言われた * それはドキュメントビルダーの仕事なのか * blockdiagにdesctable機能を付けようとしてる * contribの方で使える * noをつけると番号も付いたり * この機能があるからコメント要らないよね * でもnwdiagだといろいろ他にも表示が欲しいと言われたり * ciscoのアイコン * blockdiagcontribに入れようとしてる * shapeで画像を指定できるようになる * ラベル入れたいとか言われてどうしよう - 右下40度？ * ノードの枠はないほうがいい * アイコンがいっぱいあるのでどうしよう * zabbixのconfigをblockdiagに入れるってやつ * レイアウトしてるファイルだけでは情報が足りない * host.xml を使えばいいんじゃないかと思い、もらった。 * zabbixはホストというかインタフェースで定義してる * ノードのレベルと結びつけるのがない * raw::htmlディレクティブでcheckbox使ってる * 手書きのcheckbox ================================================================ その他のお話 ================================================================ bitbucket wikiのいけてないところ * 名前空間の分け方が分からない (sphinx/doc/20110530とか) * webインタフェースからファイルの削除ができない * てか、reSTじゃない