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