エキPy読書会 13 (2011/6/21)

日時:

2011/6/21 19:00 - 22:00

範囲:

第10章(p263～): プロジェクトのドキュメント作成

エキスパートPythonプログラミングの読書会13回目。

ドキュメント作成のための戦略について。なお10章は無料配布があります -> プロジェクトのドキュメント作成 - Sphinx-users.jp

相変わらず本を読まない読書会を目指したかったのですが、ドキュメントの章だけに文字での概念説明が多かったです＞＜

会場の様子

途中撮り忘れていたため帰り際に撮影しました。

../../../_images/13-1.jpg ../../../_images/13-2.jpg

質疑応答（覚えてる範囲）

  • 1つめと2つめのステップでツールを変えてます(@togakushi)

    • MindMapでやって、エディタでやって、3段階使ってます(@togakushi)

    • Sphinxで見た目変えるだけで誤字や微妙な表現に気づくことも(@shimizukawa)

  • 書くのは楽しくないよね(@Terapyon)

    • Sphinxにしてから楽しいよ(@togakushi)

    • テキストで先に書いた方がレバレッジがきくし整理しやすい(@kshigeru)

    • 「コード見れば分かるよ」と言う人のコードは読みにくい(@kshigeru)

    • エラー条件とか先に明示したほうが実装もきれいに行ける(@kshigeru)

    • 仕事でconfig書くよりドキュメント書いた方が楽し(@tanihito)

    • Sphinx使い始めてからdocstringのカバレッジが上がりました(@shomah4a)

  • ドキュメントポートフォリオ的なものを持っていますか？

    • Faxの送り状くらいならありますよね(@Terapyon)

    • 前のドキュメントからコピペはよくやってる(@Terapyon)

      • 参考にして、とか、踏襲して、とか言うことがよくあります(@togakushi)

      • コピペ多いですが、より新しいコピー元を使うべきなのに古いのを踏襲してしまったり(@kshigeru)

      • WordやExcelで踏襲元を間違えると大変...

      • Excelで隠されたシートがあるのに気づかず別のお客さんに出してしまって..

  • Sphinxでは1つのSphinxプロジェクトで文書を作るのが一般的？

    • 対象者を全て包含したドキュメントを作ってますが、工夫もしてます(@shimizukawa)

      • 対象者毎にディレクトリ階層を分けることで分離しやすくする

      • Sphinxでは簡単に部分階層のみでドキュメント生成が可能

  • Sphinxにはどんな出力形式がありますか?

    • html: singleとかデザイン変更とかはいっぱいある

    • pickle: pickleで辞書形式になっているのでツールで利用しやすい

    • json: json形式なのでAJAx的に利用しやすい

    • htmlhelp: Windowsのchmを生成するための元データを出力

    • qthelp: QT用？

    • latex: latexファイル等を生成,ここからPDF作成などを行う

    • changes: CHANGESのフォーマットかな？

    • linkcheck: リンク先の404,302,303,等をチェックして一覧化してくれる

    • doctest: Document中のテストを実行する

    • azw (開発中): Kindle向け

    • docx (開発中): Windows向け

参考