Successfully reported this slideshow.

More Related Content

Related Books

Free with a 14 day trial from Scribd

See all

Sphinx/reST

  1. 1. Sphinx / reST 2012/05/05 h13i32maru@Twitter maruyama-r@KLab
  2. 2. 自己紹介 • 丸山 亮(h13i32maru) 最近はJSを触ってます • KLab株式会社所属 32 http://blog.h13i32maru.jp http://twitter.com/h13i32maru https://www.facebook.com/ryo.maruyama https://github.com/h13i32maru
  3. 3. Sphinx • ドキュメント作成ツール - python製 • reStructuredText(reST)をマークアップ言語として 使っている
  4. 4. Sphinxで作られたドキュメント
  5. 5. reST • 構造化文書のためのマークアップ言語 • markdown, trac/wikiみたいなもの • 色々なフォーマットに出力できる - HTML - LaTeX - man-pages - etc...
  6. 6. マークアップ • セクション • 注釈 • 段落 • リンク • リスト • ディレクティブ • テーブル • ロール • 太文字 • etc... • イタリック
  7. 7. ディレクティブ • 高度な文書を記述するためのreSTを拡張する機能 • 標準でいくつか提供されている - 画像 - 警告 - インクルード - etc...
  8. 8. ディレクティブ書式 • 名前 .. name:: arg • 引数 :option: option-value :option: option-value • オプション content... • コンテンツ
  9. 9. 画像ディレクティブ .. image:: picture.jpeg :height: 100px :width: 200 px :scale: 50 % :alt: alternate text :align: right
  10. 10. 警告ディレクティブ .. warning:: this is not thread safe!
  11. 11. ロール • ある処理を指定されたテキストに行う機能 • インライン ディレクティブとも解釈できる • 例えばリンクを貼ったり、置き換えたり :rolename:`text` :RFC:`2822` :strong:`text`
  12. 12. Sphinxによる拡張 • プログラムドキュメントのためのディレクティ ブ/ロールを提供している •例 - toctreeディレクティブ - code-blockディレクティブ - ドメイン
  13. 13. toctree • reST文書の関連(目次)を記述するディレクティブ .. toctree:: :maxdepth: 2 intro tutorial ...
  14. 14. code-block • ソースコードの表示を行うディレクティブ(他に もc/java/ruby/javascriptなどなど) .. code-block: python def max(a, b): return a if a >= b else b
  15. 15. ドメイン • 関数の説明といったプログラム言語固有のディレ クティブ/ロールをグループにまとめて提供 - python - c - c++ - javascript - reST
  16. 16. py:function • pythonの関数ドキュメントを記述する .. py:function:: max(a, b) :param a: 比較数値 :param b: 比較数値 :return: 大きい方の値 :rtype: 数値
  17. 17. :py:func: • pythonの関数にリンクを貼る これは :py:func:`max` のラッパー 関数です。
  18. 18. 他にも • ドキュメントの検索機能 - ドキュメントビルド時にインデックス化してjs だけで検索機能を実現 • テーマの切り替え - sphinxdocテーマがおすすめ
  19. 19. 参考 • http://sphinx-users.jp/doc11/ • http://docutils.sourceforge.net/rst.html • http://www.planewave.org/translations/rst/ quickref.html#hyperlink-targets
  20. 20. おわり

×