Sphinx拡張探訪 2014 #sphinxjp

1. 小宮健(Takeshi KOMIYA) @tk0miya SphinxCon JP 2014

2. お前だれよ  仕事  (株)タイムインターメディア所属  参加コミュニティ  Sphinx-users.jp  Python mini hack-a-thon  新宿Book-a-thon  Sphinx を中心にツールを開発  blockdiag シリーズ  Sphinx 拡張機能の開発  Googlechart やカレンダー機能 Twitter: @tk0miya

3. アジェンダ  Sphinx 拡張とは  ひたすらSphinx 拡張を紹介  まとめ(時間があれば)  資料は後ほど公開します。ひたすら聞いてください。

4. Sphinx 拡張とは  Sphinx の機能を拡張するもの  マークアップ機能(reST)を拡張する  出力フォーマットを増やす、追加する  Sphinx 周辺の便利ツール  その他  プラグイン方式でSphinx をどんどん便利に

5. Sphinx 拡張とは  例えば… ?  sphinxcontrib-cacoo  Cacoo で書いた図をドキュメントに取り込む  sphinxcontrib.gist  gist の内容をドキュメントに取り込む  sphinxcontrib-fancybox  画像クリック時にポップアップ表示させる(Lightbox 化)  sphinxcontrib-dashbuilder  ドキュメントをdash 形式で出力する  sphinxcontrib-spelling  ドキュメントのスペルチェックを行う

6. Sphinx 拡張とは  Sphinx 拡張はどれくらいあるの?  200個以上あります  どこで見つけるとよいの?  PyPI で“sphinx”, “sphinxcontrib” で検索しましょう  どういうものがあるか知りたい  今回まとめました！

7. Sphinx 拡張探訪2014  @tk0miya が地道に見つけてまとめました  PyPI の検索結果をひとつずつチェック  sphinx-contrib リポジトリ  Google 検索(github, gist, bitbucket などを中心に)  その数230個  用途別に18種類に分類しました  Sphinx のテーマは含めていません

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. 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. autodoc  autodoc: ソースコードなどからドキュメントを生成する  主にAPI リファレンスに用いられる  breathe  Doxygen XML からドキュメントを生成  django-giza  Django のソースコード(Python)からドキュメントを生成  repose.sphinx.autointerface  Zope Interface (python)からドキュメントを生成  sphinxcontrib-autoprogram  argparse (python)からドキュメントを生成

11. autodoc  autodoc: ソースコードなどからドキュメントを生成する  主にAPI リファレンスに用いられる  javasphinx,  Java のソースコードからドキュメントを生成  sphinxcontrib-autojs  JavaScript のソースコードからドキュメントを生成  tk.phpautodoc  PHP のソースコードからドキュメントを生成  schem2rst  DB スキーマからデータベース定義を生成

12. autodoc  sphinx-autodoc-annotation  関数アノテーション(python3)を利用してドキュメントを生成

13. autodoc  sphinxcontrib-sqlengine  sqlengine (Cassandra の ORM) のモデルを利用

14. builders  builders: 出力先を追加する  sphinx-behat  behat (PHP のBDD Framework) の定義を出力する  sphinxcontrib-omegat  OmegaT (翻訳ツール)用のファイルを出力する  sphinxcontrib-dashbuilder  dash (API リファレンスビューア)形式で出力する  sphinxcontrib-docbookrestapi  docbook 形式で出力する

15. domains  domains: 言語ドメインを追加する  関数やクラスなど、言語固有の情報をマークアップする  各言語向けのドメインが提供されている  Java, Ruby, PHP, Erlang, Golang, Scala, Fortran, Coffee Script, Common Lisp, Emacs Lisp, Ada  ツール向けのドメインも存在する  make, cmake, Jinja Template

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. enhancement  enhancement: Sphinx の既存機能を強化する  japanesesupport.py  地の文から改行を除去し、空白が混ざってしまうのを防ぐ  sphinxcontrib_markdown  Sphinx でmarkdown を扱うための実験的な拡張  sphinxcontrib_remoteinclude  リモートのrst ファイルをinclude する

18. execute/result  execute/result: コマンドを実行し、その結果を取り込む  sphinxcontrib-autorun  Python コードやコマンドの実行結果を取り込む .. runblock:: pycon >>> from datetime import datetime >>> str(datetime.now()) .. runblock:: console $ ls

19. execute/result  execute/result: コマンドを実行し、その結果を取り込む  Understanding JSON Schema  JSON スキーマのバリデーション成否を表示する .. schema_example:: { "type": "string" } -- "I'm a string" --X 42

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. multimedia/web-services  multimedia/web-services  動画やWeb サービスのコンテンツを差し込む  動画を埋め込む  Youtube, ニコニコ動画, Flash ファイル  スライドを埋め込む  sphinxcontrib-slide (slideshare, google docs など)  その他  googlemaps, gist, twitter  sphinxcontrib-embedly

22. roles  roles: Sphinx ロールを追加する  メタ情報  Email  外部ページへのリンク  wikipedia, pypi, manpage, smblink  テキスト装飾  ruby (ルビ), del (削除線, <strike>), color  その他  bible (聖書の引用)

23. utilities  utilities: Sphinx の周辺ツール  sphinx-autobuild  変更を検知して自動的にビルドを実行する  livereload にも対応  sphinx-intl  Sphinx で記述された文書のi18n 用ラッパー  Transifex と組み合わせて翻訳する仕組みを持っている

24. Website/blogs  website/blogs: Web サイトやブログに関する拡張  Amazon アフィリエイト  RSS 生成  awesome font  google analytics  recent changes

25. Sphinx 拡張探訪2014  便利そうなSphinx 拡張をまとめました  いろいろ紹介したけど、多すぎて把握できませんね  紹介できていない拡張もまだまだあります  そこでSphinx 拡張カタログを作ってみました  Survey of Sphinx extensions  http://sphinxext-survey.readthedocs.org/en/latest/

26. Survey of Sphinx extensions  Survey of Sphinx extensions

27. Survey of Sphinx extensions  Survey of Sphinx extensions

28. Survey of Sphinx extensions  Survey of Sphinx extensions  http://sphinxext-survey.readthedocs.org/en/latest/  今回調査したSphinx拡張の情報を掲載  225個の情報  18のカテゴリに分類  最新バージョンの情報を掲載  メンテナンスを手伝ってくれる方を募集しています

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. おまけ(作者別ランキング)  トップ9に日本人が5人いる(50%)  1位の人はツイッターでアイディアを拾ってます  ツイッターでつぶやくとある日拡張ができるかも…?

31. おまけ(作者別ランキング)  トップ9に日本人が5人いる(50%)  1位の人はツイッターでアイディアを拾ってます  ツイッターでつぶやくとある日拡張ができるかも…?

32. まとめ  Sphinx 拡張を整理してみました  Survey of Sphinx extensions  http://sphinxext-survey.readthedocs.org/en/latest/  便利な拡張を見つけて、楽してドキュメントを書きましょう  #sphinxjp タグでつぶやくとなにか良いことあるかも …?

https://twitter.com	58
http://sphinxjp.connpass.com	28

SlideShare for iOS

Sphinx拡張探訪 2014 #sphinxjp

by Takeshi Komiya , テクニカルオフィサ(笑) at タイムインターメディア

on Oct 26, 2014

Statistics

Views

Actions

2 Embeds 83

Accessibility

Categories

Upload Details

Usage Rights

Report content