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

Sphinx/reST

3,624 views

Published on

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

  • Be the first to like this

No Downloads
Views
Total views
3,624
On SlideShare
0
From Embeds
0
Number of Embeds
2,258
Actions
Shares
0
Downloads
7
Comments
0
Likes
0
Embeds 0
No embeds

No notes for slide

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. おわり

×