Sphinx拡張 探訪 2014 #sphinxjp

7,135 views

Published on

Sphinx拡張 探訪 2014 #sphinxjp

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

No Downloads
Views
Total views
7,135
On SlideShare
0
From Embeds
0
Number of Embeds
4,325
Actions
Shares
0
Downloads
10
Comments
0
Likes
13
Embeds 0
No embeds

No notes for slide

Sphinx拡張 探訪 2014 #sphinxjp

  1. 1. 小宮健(Takeshi KOMIYA) @tk0miya SphinxCon JP 2014
  2. 2. お前だれよ  仕事  (株)タイムインターメディア所属  参加コミュニティ  Sphinx-users.jp  Python mini hack-a-thon  新宿Book-a-thon  Sphinx を中心にツールを開発  blockdiag シリーズ  Sphinx 拡張機能の開発  Googlechart やカレンダー機能 Twitter: @tk0miya
  3. 3. アジェンダ  Sphinx 拡張とは  ひたすらSphinx 拡張を紹介  まとめ(時間があれば)  資料は後ほど公開します。ひたすら聞いてください。
  4. 4. Sphinx 拡張とは  Sphinx の機能を拡張するもの  マークアップ機能(reST)を拡張する  出力フォーマットを増やす、追加する  Sphinx 周辺の便利ツール  その他  プラグイン方式でSphinx をどんどん便利に
  5. 5. Sphinx 拡張とは  例えば… ?  sphinxcontrib-cacoo  Cacoo で書いた図をドキュメントに取り込む  sphinxcontrib.gist  gist の内容をドキュメントに取り込む  sphinxcontrib-fancybox  画像クリック時にポップアップ表示させる(Lightbox 化)  sphinxcontrib-dashbuilder  ドキュメントをdash 形式で出力する  sphinxcontrib-spelling  ドキュメントのスペルチェックを行う
  6. 6. Sphinx 拡張とは  Sphinx 拡張はどれくらいあるの?  200個以上あります  どこで見つけるとよいの?  PyPI で“sphinx”, “sphinxcontrib” で検索しましょう  どういうものがあるか知りたい  今回まとめました!
  7. 7. Sphinx 拡張探訪2014  @tk0miya が地道に見つけてまとめました  PyPI の検索結果をひとつずつチェック  sphinx-contrib リポジトリ  Google 検索(github, gist, bitbucket などを中心に)  その数230個  用途別に18種類に分類しました  Sphinx のテーマは含めていません
  8. 8. Sphinx 拡張の分類(1) autodoc 26 ソースコードなどからドキュメント を生成する builders 11 出力先を追加する changelog/ version-control 10 Changelog やVCS に関する履歴情報 をマークアップする data-sources 3 データベースからドキュメントを生 成する domains 28 言語ドメインを追加する enhancement 28 Sphinx の既存機能を強化する execute/result 9 コマンドを実行し、その結果をド キュメントとして取り込む images 33 画像をドキュメントに差し込む integrations 4 他のドキュメントと連携する
  9. 9. Sphinx 拡張の分類(2) jokes 4 ネタ拡張 metadata 5 メタデータをマークアップする multimedia/ web-services 9 動画やWeb サービスのコンテンツ を差し込む roles 11 Sphinx ロールを追加する search 3 Sphinx の検索機能を向上させる thesis/latex 4 論文やLaTeX に関する拡張 utilities 6 Sphinx の周辺ツール website/blogs 15 Web サイトやブログに関する拡張 misc 21 その他
  10. 10. autodoc  autodoc: ソースコードなどからドキュメントを生成 する  主にAPI リファレンスに用いられる  breathe  Doxygen XML からドキュメントを生成  django-giza  Django のソースコード(Python)からドキュメントを生 成  repose.sphinx.autointerface  Zope Interface (python)からドキュメントを生成  sphinxcontrib-autoprogram  argparse (python)からドキュメントを生成
  11. 11. autodoc  autodoc: ソースコードなどからドキュメントを生成 する  主にAPI リファレンスに用いられる  javasphinx,  Java のソースコードからドキュメントを生成  sphinxcontrib-autojs  JavaScript のソースコードからドキュメントを生成  tk.phpautodoc  PHP のソースコードからドキュメントを生成  schem2rst  DB スキーマからデータベース定義を生成
  12. 12. autodoc  sphinx-autodoc-annotation  関数アノテーション(python3)を利用してドキュメント を生成
  13. 13. autodoc  sphinxcontrib-sqlengine  sqlengine (Cassandra の ORM) のモデルを利用
  14. 14. builders  builders: 出力先を追加する  sphinx-behat  behat (PHP のBDD Framework) の定義を出力する  sphinxcontrib-omegat  OmegaT (翻訳ツール)用のファイルを出力する  sphinxcontrib-dashbuilder  dash (API リファレンスビューア)形式で出力する  sphinxcontrib-docbookrestapi  docbook 形式で出力する
  15. 15. domains  domains: 言語ドメインを追加する  関数やクラスなど、言語固有の情報をマークアップす る  各言語向けのドメインが提供されている  Java, Ruby, PHP, Erlang, Golang, Scala, Fortran, Coffee Script, Common Lisp, Emacs Lisp, Ada  ツール向けのドメインも存在する  make, cmake, Jinja Template
  16. 16. domains  domains: 言語ドメインを追加する  関数やクラスなど、言語固有の情報をマークアップす る  sphinxcontrib-httpdomain (HTTP ドメイン)  HTTP API をマークアップできる .. http:get:: /users/(int:user_id)/posts/(tag) The posts tagged with `tag` that the user (`user_id`) wrote.
  17. 17. enhancement  enhancement: Sphinx の既存機能を強化する  japanesesupport.py  地の文から改行を除去し、空白が混ざってしまうのを 防ぐ  sphinxcontrib_markdown  Sphinx でmarkdown を扱うための実験的な拡張  sphinxcontrib_remoteinclude  リモートのrst ファイルをinclude する
  18. 18. execute/result  execute/result: コマンドを実行し、その結果を取り 込む  sphinxcontrib-autorun  Python コードやコマンドの実行結果を取り込む .. runblock:: pycon >>> from datetime import datetime >>> str(datetime.now()) .. runblock:: console $ ls
  19. 19. execute/result  execute/result: コマンドを実行し、その結果を取り 込む  Understanding JSON Schema  JSON スキーマのバリデーション成否を表示する .. schema_example:: { "type": "string" } -- "I'm a string" --X 42
  20. 20. images  images: 画像をドキュメントに差し込む  Sphinx では直接画像を扱えないため、多くの拡張が提 供されている  画像ファイルを取り込む  PowerPoint, gnuplot, astah, cacoo, eagle, gravater, Libre Office, visio,  マークアップから図を生成する  UML (mscgen, PlantUML, sdedit, actdiag, seqdiag, yUML)  ブロック図(aafigure, blockdiag, nwdiag)  グラフ(google chart, gruffy)
  21. 21. multimedia/web-services  multimedia/web-services  動画やWeb サービスのコンテンツを差し込む  動画を埋め込む  Youtube, ニコニコ動画, Flash ファイル  スライドを埋め込む  sphinxcontrib-slide (slideshare, google docs など)  その他  googlemaps, gist, twitter  sphinxcontrib-embedly
  22. 22. roles  roles: Sphinx ロールを追加する  メタ情報  Email  外部ページへのリンク  wikipedia, pypi, manpage, smblink  テキスト装飾  ruby (ルビ), del (削除線, <strike>), color  その他  bible (聖書の引用)
  23. 23. utilities  utilities: Sphinx の周辺ツール  sphinx-autobuild  変更を検知して自動的にビルドを実行する  livereload にも対応  sphinx-intl  Sphinx で記述された文書のi18n 用ラッパー  Transifex と組み合わせて翻訳する仕組みを持っている
  24. 24. Website/blogs  website/blogs: Web サイトやブログに関する拡張  Amazon アフィリエイト  RSS 生成  awesome font  google analytics  recent changes
  25. 25. Sphinx 拡張探訪2014  便利そうなSphinx 拡張をまとめました  いろいろ紹介したけど、多すぎて把握できませんね  紹介できていない拡張もまだまだあります  そこでSphinx 拡張カタログを作ってみました  Survey of Sphinx extensions  http://sphinxext-survey.readthedocs.org/en/latest/
  26. 26. Survey of Sphinx extensions  Survey of Sphinx extensions
  27. 27. Survey of Sphinx extensions  Survey of Sphinx extensions
  28. 28. Survey of Sphinx extensions  Survey of Sphinx extensions  http://sphinxext-survey.readthedocs.org/en/latest/  今回調査したSphinx拡張の情報を掲載  225個の情報  18のカテゴリに分類  最新バージョンの情報を掲載  メンテナンスを手伝ってくれる方を募集しています
  29. 29. おまけ(作者別ランキング) 順位名前パッケージ 数 1 Takeshi KOMIYA 24 2 Doug Hellmann 7 2 Takayuki SHIMIZUKAWA 7 4 SHIBUKAWA Yoshiki 6 4 Kay-Uwe (Kiwi) Lorenz 6 6 Sebastian Wiesner 5 7 WAKAYAMA shirou 4 7 Kirill Simonov 4 7 @shomah4a 4
  30. 30. おまけ(作者別ランキング)  トップ9に日本人が5人いる(50%)  1位の人はツイッターでアイディアを拾ってます  ツイッターでつぶやくとある日拡張ができるかも…?
  31. 31. おまけ(作者別ランキング)  トップ9に日本人が5人いる(50%)  1位の人はツイッターでアイディアを拾ってます  ツイッターでつぶやくとある日拡張ができるかも…?
  32. 32. まとめ  Sphinx 拡張を整理してみました  Survey of Sphinx extensions  http://sphinxext-survey.readthedocs.org/en/latest/  便利な拡張を見つけて、楽してドキュメントを書き ましょう  #sphinxjp タグでつぶやくとなにか良いことあるかも …?

×