Sphinx Tutorial at BPStudy#30

3,692 views
3,532 views

Published on

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

Published in: Technology
0 Comments
7 Likes
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total views
3,692
On SlideShare
0
From Embeds
0
Number of Embeds
12
Actions
Shares
0
Downloads
26
Comments
0
Likes
7
Embeds 0
No embeds

No notes for slide

Sphinx Tutorial at BPStudy#30

  1. 1. たのしいドキュメンテーション<br />For BPStudy #30, Feb,26th,2010<br />日本XPユーザグループ代表(予)<br />Python温泉(系), とちぎRuby<br />渋川よしき<br />
  2. 2. 本日のレシピ<br />座学<br />Sphinxの歴史<br />Sphinxとは何か?<br />Wikiとの比較<br />Sphinxの使い方<br />ハンズオン<br />おすすめ書籍紹介ドキュメントを作ってみよう<br />座学<br />大きなドキュメントを書くための機能<br />技術ドキュメントを書くコツ<br />Sphinxの内部構造<br />1.0以降の展開<br />
  3. 3. Sphinxのインストール<br />Linux/MacOSXな人<br />sudo port install py26-sphinxなど<br />Windowsな人<br />Pythonをインストール<br />easy_installをインストール<br />easy_inatall sphinx<br />詳しくは: http://blog.shibu.jp/article/32044108.html<br />
  4. 4. Sphinxの使い方 -流れ-<br />sphinx-quickstart<br />django-adminとか、railsコマンドみたいなもの<br />質問に答えるとフォルダができる<br />ドキュメントを作る<br />make XXX<br />HTML<br />PDFなど<br />プロジェクト<br />作成<br />ドキュメント<br />作成<br />ビルド<br />
  5. 5. Sphinxの使い方を調べるには?<br />Sphinx本体の解説<br />http://sphinx.shibu.jp/<br />reStructuredText<br />Sphinx内の入門<br />http://sphinx.shibu.jp/rest.html<br />reStructured入門<br />http://www.planewave.org/translations/rst/quickstart.ja.html<br />はやわかりreStructuredText(リファレンス)<br />http://www.planewave.org/translations/rst/quickref.html<br />Sphinxを使っているサイト<br />コード見れます<br />Taken by andercismo<br />Under CC BY-NC-SA<br />
  6. 6. プロジェクトを作ろう<br />sphinx-quickstartコマンドで作る<br />プロジェクト名、著者名、バージョン以外はEnter連打でOK<br />conf.pyを必要に応じて編集すればよい<br />既存のスケルトン<br />自分のいつも使うスタイルを<br />例:@MiCHiLUさんのsphinx-skeleton<br />プロジェクト<br />作成<br />http://bitbucket.org/MiCHiLU/sphinx-skeleton/overview/<br />
  7. 7. プレーンテキストのマークアップ<br />reStructuredTextを利用<br />ソースのままでも可読性が高い<br />拡張可能なフォーマット<br />注意点<br />日本語にはUTF-8で使おう<br />すべての異なる要素の間には空行を<br />リストの階層が変わる時も<br />ドキュメントを作ろう<br />ドキュメント<br />作成<br />
  8. 8. セクションタイトル<br />ドキュメント<br />作成<br />ドキュメントを構成する重要な要素<br />#, *, =, -, ^, ~, “などの記号で下だけ、上下を囲う<br />自分なりのルールを決めておくと良い<br />単体のソース内の登場順でH1, H2, H3..が決まる<br />文字長よりも短いと警告が出ます<br />========<br />はじめに<br />========<br />想定読者<br />========<br />新人社会人<br />----------<br />はじめに<br />想定読者<br />新人社会人<br />
  9. 9. 親子関係の定義<br />ドキュメント<br />作成<br />Sphinxの一番重要な部分(大規模ドキュメント作成時)<br />toctreeディレクティブを使って定義する<br />拡張子なしのファイル名を列挙する<br />目次がその場で作られる(:maxdepth:でレベルが変わる)<br />目次を出したくない場合には、 :hidden:をつけて、:doc:ロールで自分で索引を作る<br /> .. toctree::<br />:maxdepth: 2<br /> preface<br /> overview/index<br /> defensive/index<br /><ul><li>はじめに
  10. 10. 本書の考えるゴール
  11. 11. 本書を作るにあたって
  12. 12. 本書で説明していくこと
  13. 13. つまみぐい勉強法
  14. 14. 勉強はつまみぐいから
  15. 15. 大切なことは、継続
  16. 16. 自分に合うものを選ぼう
  17. 17. 終着点は自分で決めよう</li></li></ul><li>親子関係の定義<br />セクションタイトルを子供の文書から引っ張ってきて目次を作る<br />toctree自体は1文書に何個も書ける<br />toctree表示位置に、子供の文書のセクション構造が挿入される<br />ドキュメント<br />作成<br />toctreeを制するモノがSphinxを制す<br />
  18. 18. 箇条書き<br />ドキュメント<br />作成<br />* を前に付けると、バレットリスト<br />#, 数値 + ピリオドで、ナンバー付きリスト<br />複数階層もできます<br />ただし階層が変わる前後は空行を入れること<br /> 1.トヨタ<br /> * プリウス<br /> * クラウンハイブリッド<br /> 2. ホンダ<br /> * シビックハイブリッド<br /> * CR-Z<br />トヨタ<br /><ul><li>プリウス
  19. 19. クラウンハイブリッド</li></ul>ホンダ<br /><ul><li>シビックハイブリッド
  20. 20. CR-Z</li></li></ul><li>フィールドリスト<br />ドキュメント<br />作成<br />:項目名: 値<br />著者名、出版日などの情報を列挙したいけど、表にするまでもない時に使えます<br /> :書名: スクラム<br /> :訳者: スクラムエヴァンジ..<br /> :出版社: ピアソン<br /> :発行日: 2003/09/20<br /> :本体価格: 2000円<br /> :ISBN: 9784894715899 <br />書名:スクラム<br />訳者:スクラムエヴァンジ..<br />出版社:ピアソン<br />発行日: 2003/09/20<br />本体価格: 2000円<br />ISBN: 9784894715899 <br />
  21. 21. 画像<br />ドキュメント<br />作成<br />.. image:: ディレクティブで画像を挿入できます<br />::の後ろにファイル名を書きます<br />ファイル名は相対パスもしくは、ドキュメントのルートからの絶対パスで指定します<br />.. image:: image/tornado.png<br />
  22. 22. 外部リンク<br />ドキュメント<br />作成<br />`リンクテキスト <http://ターゲットURL>`_<br />最後のアンダースコアを忘れないように<br />日本語の文書の中に挿入する場合は、前後にスペース(もしくは¥ + スペース)を入れる<br />URLをそのまま入れる<br />リンク張ってくれます<br />分からないことがあったら `ぐぐって <http://www.google.com>`_ ください<br />参考: http://sphinx.shibu.jp<br />わからないことがあったらぐぐってください<br />参考: http://sphinx.shibu.jp<br />
  23. 23. 表(1)<br />ドキュメント<br />作成<br />書き方が4通りあります<br />一番複雑な方法<br />縦、横のセルの結合ができます<br />文字数が変わると編集が面倒<br />+-------------+----------------------+---------+---------+------+<br />| Feature List | Python2 | Python3 | Ruby |+=============+======================+=========+=========+======+<br />| Push API | following_function | O | O | |<br />+ +----------------------+---------+---------+------+<br />| | following | O | O | O |+-------------+----------------------+---------+---------+------+<br />| Pull API | Queue | O | O | _ |+-------------+----------------------+---------+---------+------+<br />
  24. 24. 表(2)<br />ややシンプルな方法<br />縦のセルの結合はできません<br />文字数が変わると編集が面倒<br />list-tableディレクティブ<br />かんたんだけど、複雑な制御はできない<br />ドキュメント<br />作成<br />======= ==== ==============<br />入力 出力<br />------------ --------------<br />種類 引数 索引<br />======= ==== ==============<br />single: A; B A -> B<br />single: A A<br />pair: A; B A -> B, B -> A<br />======= ==== ==============<br /> .. list-table::仕様<br /> :widths: 15 10 10<br /> :header-rows: 1<br />* -主要諸元<br />-MXB<br /> - MX<br />* -車両重量<br /> - 1260<br />- 1270<br />
  25. 25. 表(3)<br />csv-tableディレクティブ<br />かんたんだけど、複雑な制御はできない<br />ドキュメント<br />作成<br /> .. csv-table:: 郵便番号<br /> :header: “番号”,“住所”<br /> :width: 15, 20<br /> “321-0911”,”宇都宮市問屋町<br /> “321-0912”,”宇都宮市石井町”<br /> “321-0923”,”宇都宮氏下栗町”<br />
  26. 26. ノート、引用、コードサンプル<br />ドキュメント<br />作成<br />ブロックを挿入するために各種ディレクティブ、::記号を使う<br />インデントが終わるまで、ブロックとして扱われる<br />ブロック<br />.. note::, .. tips::, .. warning::, ::記号など<br />コードサンプル<br />.. code-block:: ディレクティブを使う<br /> .. note::<br />バージョンにより異なります<br /> .. code-block:: python<br />@auto_twitter("function")<br /> def sample_function():<br /> print “do action”<br />バージョンにより異なります<br />@auto_twitter("function")<br />defsample_function():<br />print ”do action"<br />
  27. 27. ビルド<br />コンソールからmake htmlとタイプ<br />_build/htmlフォルダ以下に出力されます<br />ビルド<br />
  28. 28. 本日のレシピ<br />座学<br />Sphinxの歴史<br />Sphinxとは何か?<br />Wikiとの比較<br />Sphinxの使い方<br />ハンズオン<br />おすすめ書籍紹介ドキュメントを作ってみよう<br />座学<br />大きなドキュメントを書くための機能<br />技術ドキュメントを書くコツ<br />Sphinxの内部構造<br />1.0以降の展開<br />
  29. 29. ハンズオン(30分)おすすめ書籍紹介ドキュメントを作ってみよう<br />二人一組になってください<br />Sphinxインストールが完了していない人は完了している人とペアを作ってください<br />効率を重視する場ではないのでエディタ論争は禁止<br />説明した機能をどんどん使って見ましょう<br />練習のために1冊1ファイルで。目標は2冊。<br />分からないことがあれば聞いてください<br />

×