Diese Präsentation wurde erfolgreich gemeldet.
Wir verwenden Ihre LinkedIn Profilangaben und Informationen zu Ihren Aktivitäten, um Anzeigen zu personalisieren und Ihnen relevantere Inhalte anzuzeigen. Sie können Ihre Anzeigeneinstellungen jederzeit ändern.

Sphinx Tutorial at BPStudy#30

4.220 Aufrufe

Veröffentlicht am

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

Veröffentlicht in: Technologie
  • Als Erste(r) kommentieren

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 />

×