BPStudy #30で説明する内容の抜粋です。ハンズオンで使用しそうなものだけ先にアップします

1. たのしいドキュメンテーションFor BPStudy #30, Feb,26th,2010日本XPユーザグループ代表(予)Python温泉(系), とちぎRuby渋川よしき

2. 本日のレシピ座学Sphinxの歴史Sphinxとは何か？Wikiとの比較Sphinxの使い方ハンズオンおすすめ書籍紹介ドキュメントを作ってみよう座学大きなドキュメントを書くための機能技術ドキュメントを書くコツSphinxの内部構造1.0以降の展開

3. SphinxのインストールLinux/MacOSXな人sudo port install py26-sphinxなどWindowsな人Pythonをインストールeasy_installをインストールeasy_inatall sphinx詳しくは: http://blog.shibu.jp/article/32044108.html

4. Sphinxの使い方 -流れ-sphinx-quickstartdjango-adminとか、railsコマンドみたいなもの質問に答えるとフォルダができるドキュメントを作るmake XXXHTMLPDFなどプロジェクト作成ドキュメント作成ビルド

5. Sphinxの使い方を調べるには？Sphinx本体の解説http://sphinx.shibu.jp/reStructuredTextSphinx内の入門http://sphinx.shibu.jp/rest.htmlreStructured入門http://www.planewave.org/translations/rst/quickstart.ja.htmlはやわかりreStructuredText(リファレンス)http://www.planewave.org/translations/rst/quickref.htmlSphinxを使っているサイトコード見れますTaken by andercismoUnder CC BY-NC-SA

6. プロジェクトを作ろうsphinx-quickstartコマンドで作るプロジェクト名、著者名、バージョン以外はEnter連打でOKconf.pyを必要に応じて編集すればよい既存のスケルトン自分のいつも使うスタイルを例：@MiCHiLUさんのsphinx-skeletonプロジェクト作成http://bitbucket.org/MiCHiLU/sphinx-skeleton/overview/

7. プレーンテキストのマークアップreStructuredTextを利用ソースのままでも可読性が高い拡張可能なフォーマット注意点日本語にはUTF-8で使おうすべての異なる要素の間には空行をリストの階層が変わる時もドキュメントを作ろうドキュメント作成

8. セクションタイトルドキュメント作成ドキュメントを構成する重要な要素#, *, =, -, ^, ~, “などの記号で下だけ、上下を囲う自分なりのルールを決めておくと良い単体のソース内の登場順でH1, H2, H3..が決まる文字長よりも短いと警告が出ます========はじめに========想定読者========新人社会人----------はじめに想定読者新人社会人

9. 親子関係の定義ドキュメント作成Sphinxの一番重要な部分(大規模ドキュメント作成時)toctreeディレクティブを使って定義する拡張子なしのファイル名を列挙する目次がその場で作られる(:maxdepth:でレベルが変わる)目次を出したくない場合には、 :hidden:をつけて、:doc:ロールで自分で索引を作る .. toctree:::maxdepth: 2 preface overview/index defensive/indexはじめに

10. 本書の考えるゴール

11. 本書を作るにあたって

12. 本書で説明していくこと

13. つまみぐい勉強法

14. 勉強はつまみぐいから

15. 大切なことは、継続

16. 自分に合うものを選ぼう

17. 終着点は自分で決めよう親子関係の定義セクションタイトルを子供の文書から引っ張ってきて目次を作るtoctree自体は1文書に何個も書けるtoctree表示位置に、子供の文書のセクション構造が挿入されるドキュメント作成toctreeを制するモノがSphinxを制す

18. 箇条書きドキュメント作成* を前に付けると、バレットリスト#, 数値 + ピリオドで、ナンバー付きリスト複数階層もできますただし階層が変わる前後は空行を入れること 1.トヨタ * プリウス * クラウンハイブリッド 2. ホンダ * シビックハイブリッド * CR-Zトヨタプリウス

19. クラウンハイブリッドホンダシビックハイブリッド

20. CR-Zフィールドリストドキュメント作成:項目名: 値著者名、出版日などの情報を列挙したいけど、表にするまでもない時に使えます :書名: スクラム :訳者: スクラムエヴァンジ.. :出版社: ピアソン :発行日: 2003/09/20 :本体価格: 2000円 :ISBN: 9784894715899 書名:スクラム訳者:スクラムエヴァンジ..出版社:ピアソン発行日: 2003/09/20本体価格: 2000円ISBN: 9784894715899

21. 画像ドキュメント作成.. image:: ディレクティブで画像を挿入できます::の後ろにファイル名を書きますファイル名は相対パスもしくは、ドキュメントのルートからの絶対パスで指定します.. image:: image/tornado.png

22. 外部リンクドキュメント作成`リンクテキスト <http://ターゲットURL>`_最後のアンダースコアを忘れないように日本語の文書の中に挿入する場合は、前後にスペース(もしくは¥ + スペース)を入れるURLをそのまま入れるリンク張ってくれます分からないことがあったら `ぐぐって <http://www.google.com>`_ ください参考: http://sphinx.shibu.jpわからないことがあったらぐぐってください参考: http://sphinx.shibu.jp

23. 表(1)ドキュメント作成書き方が4通りあります一番複雑な方法縦、横のセルの結合ができます文字数が変わると編集が面倒+-------------+----------------------+---------+---------+------+| Feature List | Python2 | Python3 | Ruby |+=============+======================+=========+=========+======+| Push API | following_function | O | O | |+ +----------------------+---------+---------+------+| | following | O | O | O |+-------------+----------------------+---------+---------+------+| Pull API | Queue | O | O | _ |+-------------+----------------------+---------+---------+------+

24. 表(2)ややシンプルな方法縦のセルの結合はできません文字数が変わると編集が面倒list-tableディレクティブかんたんだけど、複雑な制御はできないドキュメント作成======= ==== ==============入力 出力------------ --------------種類 引数 索引======= ==== ==============single: A; B A -> Bsingle: A Apair: A; B A -> B, B -> A======= ==== ============== .. list-table::仕様 :widths: 15 10 10 :header-rows: 1* -主要諸元-MXB - MX* -車両重量 - 1260- 1270

25. 表(3)csv-tableディレクティブかんたんだけど、複雑な制御はできないドキュメント作成 .. csv-table:: 郵便番号 :header: “番号”,“住所” :width: 15, 20 “321-0911”,”宇都宮市問屋町 “321-0912”,”宇都宮市石井町” “321-0923”,”宇都宮氏下栗町”

26. ノート、引用、コードサンプルドキュメント作成ブロックを挿入するために各種ディレクティブ、::記号を使うインデントが終わるまで、ブロックとして扱われるブロック.. note::, .. tips::, .. warning::, ::記号などコードサンプル.. code-block:: ディレクティブを使う .. note::バージョンにより異なります .. code-block:: python@auto_twitter("function") def sample_function(): print “do action”バージョンにより異なります@auto_twitter("function")defsample_function():print ”do action"

27. ビルドコンソールからmake htmlとタイプ_build/htmlフォルダ以下に出力されますビルド

28. 本日のレシピ座学Sphinxの歴史Sphinxとは何か？Wikiとの比較Sphinxの使い方ハンズオンおすすめ書籍紹介ドキュメントを作ってみよう座学大きなドキュメントを書くための機能技術ドキュメントを書くコツSphinxの内部構造1.0以降の展開

29. ハンズオン(30分)おすすめ書籍紹介ドキュメントを作ってみよう二人一組になってくださいSphinxインストールが完了していない人は完了している人とペアを作ってください効率を重視する場ではないのでエディタ論争は禁止説明した機能をどんどん使って見ましょう練習のために１冊1ファイルで。目標は2冊。分からないことがあれば聞いてください