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-quickstart django-adminとか、railsコマンドみたいなもの 質問に答えるとフォルダができる ドキュメントを作る make XXX HTML PDFなど プロジェクト 作成 ドキュメント 作成 ビルド

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

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

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

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

10. 本書の考えるゴール

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

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

13. つまみぐい勉強法

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

15. 大切なことは、継続

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

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 -> B single: A A pair: 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冊。 分からないことがあれば聞いてください