Sphinx拡張 探訪 / Explor Extensions ========================================== (発表時はsphinxjp.themes.htmlslideのテーマで発表しました) / (Used sphinxjp.themes.htmlslide when I had this presentation.) おまえだれよ? / Who are you? --------------------------------- - わかやましろう (Twitter: r_rudi) / Shirou WAKAYAMA | - sphinxとか / Sphinx - blockdiagとか / blockdiag - Whoosh(PurePython全文検索)とか / Whoosh(pure python full-text search) ほかには / other - PostgreSQLとか - mercurialとか ちょっと宣伝: dipus / commercial: dipus --------------------------------------------- - お手軽全文検索サーバー / light-use full-text search server - ローカルホストだとほぼ設定必要なし / You don't need any settings if you run under localhost. - builder付きでsphinxとの連携が簡単! / Builder included! easy to use by sphinx - sphinx-build -b dipus source build - 複数ドキュメントの串刺し検索も可能 / search from Multi-document. - http://tdoc.info:9876 今日のAgenda -------------- ひたすら今あるたくさんの拡張についてしゃべります / Speak extentions. Only that! Sphinxの魅力 / (One of )Sphinx Good point ----------------------------------------------- - **多彩な拡張** / ManyMany extentions pip search sphinx → 100以上! / Over 100! 拡張の種類 / Extension classification ----------------------------------------- 分類してみた / Tentatively classified 1. 言語などのドメイン / language domain 2. テーマ / theme 3. グラフなど描画系 / drawing like graph 4. excelなどの変換系 / transrator 5. Django/Zope などとの連携 / Django/zope 6. その他 / misc 言語ドメインとは? / What is the language domain ---------------------------------------------------- - マークアップ(ディレクティブとロール) / markup (directive/role) - 各種言語の構成要素 / language specific で出来てる。 / it consists. 例えば / example ---------------------- - C, C++, JSは標準添付 - ruby, php, coffee - erlang, scala - httpdomain, jinja2 - 10個以上 / over 10 sphinxcontrib-erlangdomain ------------------------------------------------ .. code-block:: rst .. erl:function:: append(ListOfLists) -> List1 :type ListOfLists: [[term()]] :rtype: [term()] .. erl:function:: append(ListOfLists) -> List1 :type ListOfLists: [[term()]] :rtype: [term()] sphinxcontrib-httpdomain ---------------------------------- .. code-block:: rst http:get:: /users/(int:user_id)/posts/(tag) :query sort: ``hit`` か ``created-at`` :query offset: オフセット. 初期値 は 0 / offset. default is 0 :query limit: 上限 初期値 は 30 / limit default is 30 :statuscode 200: 正常 / OK :statuscode 404: ユーザーが存在しない / user not found sphinxcontrib-httpdomain ---------------------------------- .. http:get:: /users/(int:user_id)/posts/(tag) :query sort: ``hit`` か ``created-at`` :query offset: オフセット. 初期値 は 0 / offset. default is 0 :query limit: 上限 初期値 は 30 / limit default is 30 :statuscode 200: 正常 / OK :statuscode 404: ユーザーが存在しない / user not found sphinxcontrib-eagle ----------------------- eagleとは / what is eagle プリント基板とかを作れる言語、らしい / I heard it is to-make-hardware-board language :: .. eagle-image:: singlesided.sch :resolution: 100 :scale: 30 % eagle 結果 / result ------------------------- .. figure:: img/eagle.png :scale: 90% :align: center テーマ/ theme --------------------- 各種テーマも拡張として配られています。 / many themes are distributed as an extention sphinxjp.themecore テーマ拡張の基盤 / core util of theme extention. このスライドも実は拡張の一つです / This slide is one of theme extention sphinxjp.themes.htmlslide sphinxjp.themes.solarized ---------------------------------- .. figure:: img/solarized.png :scale: 80% :align: center cloud_sptheme ---------------------- .. figure:: img/cloud.png :scale: 80% :align: center グラフなどの描画系 / drawing ------------------------------ - blockdiagシリーズ - gnuplot - graphviz - googlechart - nicovideo / youtube ... sphinxcontrib-googlechart ソース ---------------------------------------- .. code-block:: rst .. piechart3d:: :size: 480x240 dog: 100 cat: 80 rabbit: 40 googlechart 描画例 / example ---------------------------------- .. piechart3d:: :size: 700x400 dog: 100 cat: 80 rabbit: 40 sphinxcontrib-nicovideo ---------------------------- :: .. nicovideo:: sm9 .. nicovideo:: sm9 (nicovideo is a video site like the Youtube) sphinxcontrib-aafig ---------------------------- .. code-block:: rst .. aafig:: :aspect: 60 :width: 600 :height: 300 :proportional: :textual: :class: aafig +-------+ +-----------+ | Hello +-------->+ aafigure! | +-------+ +-----------+ sphinxcontrib-aafig ---------------------------- .. aafig:: :aspect: 60 :width: 600 :height: 300 :proportional: :textual: :class: aafig +-------+ +-----------+ | Hello +-------->+ aafigure! | +-------+ +-----------+ sphinxjp.shibukawa -------------------- カレンダー描画 / Drawing calender .. code-block:: rst .. schedule:: item1: 9/1 - 9/3 item2: 9/4 - 9/10 item3: 9/5 - 9/7 .. schedule:: item1: 9/1 - 9/3 item2: 9/4 - 9/10 item3: 9/5 - 9/7 excelなどの変換系 / Translator ----------------------------------- wiki2sphinx moin-moin wikiからrestに変換 / from moin-moin wiki sphinxcontrib-exceltable Excelから変換 / from Excel odt2sphinx OpenDocumentから変換 / from OpenDocument sphinx-git git changelogを変換 / from changelog nose-sphinx-doc noseのテストから変換 / from nose testing sphinxcontrib-exceltable ----------------------------- .. code-block:: rst .. exceltable:: Table caption :file: img/sphinxcon2012-test.xls :header: 1 :selection: A1:B3 .. figure:: img/xls-shot.png exceltable 結果 / result ----------------------------- | .. exceltable:: Table caption :file: img/sphinxcon2012-test.xls :header: 1 :selection: A1:B3 sphinx-git --------------- .. code-block:: rst .. git_changelog:: .. git_changelog:: Django/Zope などとの連携 / Integration with Django/Zope ------------------------------------------------------------- **ごめんなさい。試せてません ><** / **Sorry! not yet** django-documentation djangoのドキュメントを自動生成 / document automake wuxi djangoのテンプレートをsphinxで使う? / using django template in sphinx?? その他 / misc --------------------- 分類に困ったもの / These are hard to classifier. 実はこれが一番多い / Actually, the number is top. sphinxcontrib-osaka ----------------------- 大阪弁フィルタ / Filter to osaka dialect 勝手に大阪弁になります。 / made osaka dialect without asking (前会長作) / created by former chairman sphinxcontrib-issuetracker -------------------------------- :: :issue:`{issue.title} (#{issue.id}) <33>` と書くとリンクを貼ってくれる / crete link :issue:`{issue.title} (#{issue.id}) <33>` github, bitbucket, launchpad, google code, debian, jira に対応 自分で好きにURLを生成も可能 / or set your own URL sphinxfeed ------------ RSSフィードを生成してくれる。 / generate RSS feed conf.pyに以下のように記載する。 / write below in conf.py .. code-block:: rst feed_base_url = 'http://YOUR_HOST_URL' feed_author = 'YOUR NAME' sphinxcontrib.spelling ------------------------------ PyEnchantというスペルチェックライブラリを使い、ドキュメントのスペルチェックをしてくれる。ドキュメントごとに辞書をもてたりする。 / Document spellcheck using PyEnchant. This can own a dictonary per document. .. code-block:: bash % sphinx-build -b spelling source build Running Sphinx v1.1.3 ... Spelling checker messages written to ./docs/build/spelling/output.txt そのほか / other -------------------- sphinxcontrib-googleanalytics analytics貼り付けを便利に / for google analytics sphinx-gettext-helper gettextを便利に / for gettext builder sphinxtogithub github pagesに書き出してくれる / write for github pages sphinxcontrib-bibtex bibtexファイルを使って文献目録を作れる / bibtex まとめ / conclusion ----------------------- - Sphinxは豊富な拡張も魅力 / Extension is one of good thing of Sphinx - そのうちのごく一部を紹介しました / Introduce one of them - 今回調べて新しい発見がいくつもありました - 「こんなのが欲しい!でも無いな…」 / "I want like this, but not yet..." - sphinx-users-jpへ! / Write sphinx-users-jp ML - ハッシュタグ  #sphinxjp / or hashtag .. collective.sphinx.includedoc sphinxcontrib-sqltable sphinxcontrib-bitbucket omegat numpydoc sphinxcontrib-rawfiles