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