[20101203] ドキュメントを作りたくなってしまう魔法のツールsphinx（山口発表用）

自己紹介

� 山口能迪（やまぐちよしふみ） �  id : ymotongpoo

� 「とんぷー」と呼んでください

� OSSのドキュメント翻訳をしています �  Tornado （軽量Webフレームワーク） �  Redis （高機能KVS） �  Jinja2 （テンプレートエンジン）など

お品書き

� デモ 1.  Sphinxのインストール 2.  Sphinxプロジェクトの作成 3.  reSTによるドキュメント作成 4.  Sphinxによるドキュメントのビルド

�  応用例（ビルド、テンプレート） �  サイト �  拡張について

1/4 Sphinxのインストール

�  2分で始めましょう！

� 必要なもの �  Python, easy_install, Sphinxの3点セット � パッケージ管理ツールを使えば一瞬

�  Ubuntu

�  Mac OS X

� 準備完了です

$ sudo apt-‐get install python-‐sphinx

$ sudo port install python-‐sphinx

2/4 Sphinxプロジェクトの作成

�  “sphinx-‐quickstart”を使います

� とりあえずはEnterを連打！ �  conf.pyとディレクトリが作成

� この3つだけは回答する � プロジェクト名 � バージョン番号 � 著者名

$ mkdir Unix-‐How-‐to $ cd Unix-‐How-‐to $ sphinx-‐quickstart

Demo

. ├── Makefile�├── _build �├── _static�├── _templates�├── conf.py �├── index.rst�└── make.bat�

3/4 reSTによるドキュメント作成

�  reST = reStructuredText �  http://sphinx-‐users.jp/doc10/rest.html

� テキストでも見やすい形 � 見出し � コードブロック（ハイライト付き） � 文書内／文書外リンク � 表

�  toctreeなどを作成する

============ 大見出し ============ 中見出し ========= 小見出し -‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐ -‐ リストアイテム1 -‐ リストアイテム2 #. 自動採番アイテム1 #. 自動採番アイテム2

Demo

4/4 Sphinxによるドキュメントのビルド

� 自動作成されたMakefileをそのまま利用するだけ

============ 大見出し ============ 見出し ========= -‐ リストアイテム1 -‐ リストアイテム2 #. 自動採番アイテム1 #. 自動採番アイテム2

大見出し中見出し・リストアイテム1 ・リストアイテム2 1. 自動採番アイテム1 2. 自動採番アイテム2

$ make html

Demo

応用例 1/2

� HTML以外にもデフォルトでLaTeX、PDF 、ePubに

� HTMLもデフォルトで複数のテーマを使用可

$ make latex $ make latexpdf $ make epub

Demo

テンプレートの作成

� テンプレートエンジン “Jinja2”を利用している

� 大まかに分けて2つのhtmlを作成する � ドキュメント全体の基礎 : layout.html � 各ページ : page.html

� デフォルトテーマ basic のテンプレート継承により時間が削減

自分でテンプレートを作成することも可能

Sphinx実用例

� 多くのOSSドキュメントやサイトで採用実績あり �  Python 2.6.2ドキュメント � OpenPNE Web API仕様書 �  groongaドキュメント…他多数

� テンプレート機能を用いてサイトを構成

Sphinxドメイン

� ある言語を説明するマークアップとSphinx内のオブジェクトのリンク �  Python以外にも多くの言語に対応&独自に作成可能

(Erlang, Ruby, C++, JavaScript…)

� ドキュメント内で相互参照が可能例) C .. c:function:: int printf(const char *format, …)

Sphinx拡張

� 拡張をすることで様々な要求に対応できる � 新たな出力形式に対応したい � マークアップを拡張したい

�  Sphinx拡張とは言うもののデフォルトで組み込まれている拡張が多数！

組み込みのSphinx拡張

�  autodoc – docstring からの読み込み �  intersphinx – 他のSphinxドキュメントへのリンク �  pngmath – 数式をPNG画像にレンダリング �  jsmath – JavaScriptを用いて数式をレンダリング �  graphviz – Graphvizのグラフを追加 �  coverage – ドキュメントのカバレッジ状況の収集 �  todo – Todoアイテムのサポート他にも多くの組み込みSphinx拡張あり

サードパーティのSphinx拡張

� その他特筆すべき拡張 �  sdedit

�  UMLを描けます！

�  blockdiag �  ブロック遷移図を簡単な記述だけで作成

�  docx �  SphinxでWordファイルを作成

sdedit (Quick Sequence Diagram Editor)

� UML図をテキストから生成するツール

.. sequence-‐diagram:: :maxwidth: 500 :linewrap: false :threadnumber: true actor:Actor sphinx:Sphinx[a] dot:Graphviz sdedit:Quick Sequence Diagram Editor actor:sphinx.make html sphinx:dot.render_diagram() sphinx:sdedit.render_diagram()

blockdiag by @tk0miya

� ブロック遷移図を文字のみで書けます �  sphinxcontrib-‐blockdiag でSphinxでブロック遷移図を書くことが可能

.. blockdiag:: diagram webapp { login -‐> something -‐> logout -‐> login }

docx

�  SphinxからWord形式で出力する拡張

� 現在誠意開発中 by 清水川さん

まとめ

�  Sphinxは � インストールが簡単 � 設定も簡単 � 書くのも簡単 � ビルドも簡単 � カスタマイズも簡単 � 拡張もできる � サイトも作れるという素晴らしいドキュメントツールだった！

Documents

[20101203] ドキュメントを作りたくなってしまう魔法のツールsphinx（山口発表用）