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