Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

Sphinx拡張 探訪 2014 #sphinxjp

9,208 views

Published on

Sphinx拡張 探訪 2014 #sphinxjp

Published in: Technology
  • Be the first to comment

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 タグでつぶやくとなにか良いことあるかも …?

×