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じゃない