Embed Size (px)
DESCRIPTION
http://sphinx-users.jp/event/20101203_jus_benkyoukai.html日本UNIXユーザ会 2010年12月勉強会 (2010/12/3)日本UNIXユーザ会の2010年12月の勉強会にて、以下の内容で発表させていただきました。「ドキュメントを作りたくなってしまう魔法のツール Sphinx」
Citation preview
Sphinx-‐users.jp 渋川よしき、山口能迪、清水川貴之
日本UNIXユーザ会 2010年12月勉強会
自己紹介
山口能迪（やまぐちよしふみ） id : ymotongpoo
「とんぷー」と呼んでください
OSSのドキュメント翻訳をしています Tornado （軽量Webフレームワーク） Redis （高機能KVS） Jinja2 （テンプレートエンジン） など
自己紹介：渋川よしき
仕事 大手製造業の社内SE 社外で技術習得して社内で楽をする
参加コミュニティ SphinxUsers.jp会長
翻訳ハッカソンとかを継続開催予定 日本XPユーザグループ代表 とちぎRuby Python温泉(系)
11/14にPython Hack-‐a-‐thon 今年出した本
IT業界を楽しく生き抜くための つまみぐい勉強法(技術評論社)
エキスパートPythonプログラミング (アスキーメディアワークス
電子出版文書フォーマット技術動向調査(インプレスR&D)
Twitter: @shibukawa
写真: 清水川webより転載
自己紹介： 清水川 貴之
http://清水川.jp/ @shimizukawa
オープンソースコミュニティー活動: Sphinx-‐users.jp 副会長 Zope/Plone 運営 その他, pyspa系, XP系
言語: Python, Rails, 昔はC++/C/8086
仕事: フリーでPython/Railsやってます
翻訳本 エキスパートPythonプログラミング
アスキー・メディアワークス B5変 416ページ
3分説明
プレーンテキストのファイルから、各種形式のファイルをエクスポートするプログラム
拡張機能で、機能を追加していくことができる ドキュメントは100%日本語化されている
sphinx-‐user.jp 強力なコードハイライト 利用実績多数！
国内： http://sphinx-‐users.jp/example.html 国外： http://sphinx.pocoo.org/examples.html
お品書き
デモ 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 Deiagram 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は インストールが簡単 設定も簡単 書くのも簡単 ビルドも簡単 カスタマイズも簡単 拡張もできる サイトも作れる という素晴らしいドキュメントツールだった！
ドキュメントを書くのに、何を使用していますか？
ワープロソフト Word 一太郎 OpenOffice Writer
MicrosoftのOfficeの テンプレートのサイトより転載
ドキュメントを書くのに、何を使用していますか？
表計算 Excel Calc
MicrosoftのOfficeの テンプレートのサイトより転載
ドキュメントを書くのに、何を使用していますか？
プレゼンテーション PowerPoint KeyNote OpenOffice Impress
ドキュメントを書くのに、何を使用していますか？
それ以外 Wiki HTML手書き TeX
Word Excel
Sphinx Wiki
http://www.flickr.com/photos/boothy/26461481/ CC BY-‐NC by Dr Snafu
http://www.flickr.com/photos/omeyamapyonta/3052096093/ CC BY-‐SA by PYONKO
http://www.flickr.com/photos/johncarleton/2367673332/ CC BY-‐NC-‐SA by John Carleton
http://www.flickr.com/photos/stompy/11300916/ CC BY-‐NC by Abizern
Word -‐ pros
縦書きで編集できる 文法チェックしてくれる 差分比較機能がある 参考文献、索引、 差し込み印刷etc…
http://www.flickr.com/photos/jetalone/861945664/ CC BY by jetalone
Word -‐ cons
巨大な1ファイルになる 探すのが大変 複数人で編集が大変 章の入れ替えとか厳しい
http://www.flickr.com/photos/jetalone/861945664/ CC BY by jetalone
Excel -‐ pros
Excel扱える人は多い ぱっと作るのは早くできる ロジカルシンキング的に苦心しなくても、罫線で武装すると、見た目が立派に見える
http://www.flickr.com/photos/21183810@N00/4366518191/ CC BY-‐NC-‐SA by Jerome Rothermund
Excel -‐ cons
ワークシートで分断され、閲覧性が悪い 内容の追加でレイアウトの修正が必要になると、修正に膨大な時間がかかる
http://www.flickr.com/photos/21183810@N00/4366518191/ CC BY-‐NC-‐SA by Jerome Rothermund
Wiki -‐ pros
圧倒的に柔軟 構造化されていなくても、とりあえず入れておける
複数人での編集・閲覧ができる
http://www.flickr.com/photos/7506006@N07/1197395511/ CC BY-‐NC-‐ND by milky.way
Wiki -‐ cons
文章の構成、質の維持に目を光らせる必要がある あるいは、Wikipediaのように構成を決めておく
全体の構成を修正するのに手間がかかる トップダウン型ではないので、まとめて印刷や他形式に変換がやりにくい
http://www.flickr.com/photos/7506006@N07/1197395511/ CC BY-‐NC-‐ND by milky.way
Sphinx -‐ pros
ドキュメントの背骨がしっかりさせる 有機的に文章を繋げる仕組みを持っている
説明ユニット プレーンテキスト。バージョンコントロールOK！
http://www.flickr.com/photos/18261299@N00/4472408386/ CC BY-‐SA by sweet_redbird
Sphinx -‐ cons
背骨を気にして、コンテンツを追加する必要 マークアップを覚える WYSIWIGではない
http://www.flickr.com/photos/18261299@N00/4472408386/ CC BY-‐SA by sweet_redbird
成長のポイント
背骨 toctree！toctree！toctree！
神経のネットワーク セマンティックスを定義していく
背骨の肝：セクションタイトル
ドキュメントを構成する重要な要素 #, *, =, -‐, ^, ~, “などの記号で下だけ、上下を囲う
自分なりのルールを決めておくと良い 単体のソース内の登場順でH1, H2, H3..が決まる 文字長よりも短いと警告が出ます
======== はじめに ========
想定読者 ========
新人社会人
----------
はじめに
想定読者
新人社会人
背骨の肝：親子関係の定義
Sphinxの一番重要な部分 toctreeディレクティブを使って定義する
拡張子なしのファイル名を列挙する 目次がその場で作られる
.. toctree:: :maxdepth: 2
preface overview/index defensive/index
はじめに 本書の考えるゴール 本書を作るにあたって 本書で説明していくこと
つまみぐい勉強法 勉強はつまみぐいから 大切なことは、継続 自分に合うものを選ぼう 終着点は自分で決めよう
背骨の肝：親子関係の定義
セクションタイトルを子供の文書から引っ張ってきて目次を作る
toctree自体は1文書に何個も書ける toctree表示位置に、子供の文書のセクション構造が挿入される
toctreeができたら、Sphinx黒帯！
どこからどう書いていく？
神経ネットワーク
巨大なドキュメントをどう作る？
神経ネットワーク
巨大なソフトウェアをどう作る？
• モジュール化 • 単独のプログラム+シェル(UNIX的アプローチ) • 公開インタフェースによるアクセス(粗結合) • メタプログラミング
セマンティック
定義(説明ユニット)とそこへのリンク ソースコードの構成要素の説明とリンク
.. module:: berrymq
.. function:: talk(識別子)
メッセージを送ります
クライアントとコネクションを張っ
たら :func:`talk` が使えるようになります
berrymq.talk(識別子)! メッセージを送ります"
クライアントとコネクションを張ったら talk() が使えるようになります
ディレクティブ ロール
.. _名前: :ref:`名前`
.. function:: 名前 :func:`名前`
.. method:: 名前 :meth:`名前`
ディレクティブ ロール
.. module:: 名前 :mod:`名前`
.. class:: 名前 :class:`名前`
.. attr:: 名前 :attr:`名前`
ドキュメントのモチベーションを上げ
いろんなやる気のスイッチを活用 全体像を見て、足りない項目を補完 とにかく、細かい部分から徹底的に丁寧に 索引を見て、索引を充実させる 読む人ごとの入り口を作ってみる いろんなフォーマットで出力してみる
対象 • ソフトウェア開発プロジェクト • 規模：１名～１０名前後
ドキュメント、書いてますか？
ソフトウェア開発プロジェクト 規模：１名～１０名前後
ドキュメントを書いている割合
40%くらいは書いてる？
60% 書いていない
ドキュメントが書けない開発現場
なぜドキュメントを書けないの？
どこに書いて良いか分からない 何を書いて良いか分からない どう書いて良いか分からない どんなツールを使えばいいか分からない どこに置けばいいか分からない どうせドキュメントなんて誰も見ない ドキュメントはあとで書けばいい ドキュメントを書く時間がない めんどくさい 楽しくない
ω･`)
・・・
意味あるドキュメントを書いている割合
？
問題と対策
ドキュメント作成をさぼってしまう原因
原因を取り除いてしまおう
どういう構成で書いたら良いか分からない
自分は文章を書くのが苦手だ
誰も見ない文章は書きたくない
開発終了に向かうにつれて時間がなくなる
プロジェクト開始時に構成を整備しておく
書き方の指針を決めておく
能動的にドキュメントを書くよう動機づける
先にドキュメントを書くようにする
簡単！ 面倒..
ゴール
1. ドキュメントを簡単に書けるようにする
2. みんなが能動的にドキュメントを書くように 動機付ける
3. 開発物の品質向上へフィードバックする
4. 今回の成果から構成のスケルトンを作成し 再利用する
ドキュメントを簡単に書けるようにする
簡単に書ける、って何だろう？
ドキュメンテーションの速度アップ
始めのハードルを下げて スピーディーに書けるようにしよ
う
書き方のルールを決めておく
「技術文書を書くための7つのルール」を押さえておこう！
1. ２つのステップで書く 2. 読者のターゲットを明確にする 3. シンプルなスタイルを使用する 4. 情報のスコープを絞る 5. 実在するようなコードのサンプルを使用する 6. なるべく少なく、かつ十分なドキュメント 7. テンプレートの使用
「エキスパートPythonプログラミング」 10章 （アスキーメディアワークス刊）より抜粋
10章: プロジェクトのドキュメント作成 （無料公開中）
読者ターゲット別に大きく分ける
誰が読むべきものかを意識して構成を作る。 例えば以下のように構成。
マネージャ向け 設計者向け 開発者向け 運用者向け APPENDIX
ドキュメントを書くための手間を減らす
開始時に分かっている共有情報を 予め書いておく
数ステップでドキュメントを書く環境を 整えられるようにする
共有や閲覧の仕組みを自動化して 開発プロセスに組み込む
デモ
もし今日の発表者3名がJUS商事の『サービス基盤構築』を開発したら
Step1 Sphinxの初期ドキュメントから始める
C:\> sphinx-‐quickstart
Step2 ドキュメントの最初のアウトプットを作成
読者のターゲット別に章節の構成をおおまかに用意
Step3 既に分かっている情報を追加
マネージャー、設計者、開発者それぞれに必要となる、 プロジェクト特有の情報を記載
Step4 段階的にドキュメントに記載
プロジェクトの進捗と共に 成長するドキュメント
必要な文章を必要な時に書くようにする
いつドキュメントを更新する？
いつでも！
ドキュメント駆動開発
まず目的を書こう
デモ
Pythonのドキュメント駆動開発
能動的にドキュメントを書く動機付け
品質へのフィードバック
繋がりを加速する
自動化のすゝめ
ドキュメント作成を開発サイクルに組み込む
継続的インテグレーション
課題管理
環境構築
リポジトリ
自動テスト
環境構築
自動テスト
本番環境
環境構築
ドキュメント 生成
ドキュメント 生成
実装 ドキュメンテーション
XP祭り2010 資料より抜粋 Pythonで アジャイル開発サイクル 2010ver.
http://清水川.jp/docs/xpfest2010/
全てを一体に
全体が繋がる楽しさ！
次の開発のために
ドキュメントポートフォリオへの昇華
「エキスパートPythonプログラミング」 10章 （アスキーメディアワークス刊）より抜粋
10章: プロジェクトのドキュメント作成 （無料公開中）
まとめ
1. ドキュメントを簡単に書けるようにする ７つのルールと構成のテンプレート化
2. みんなが能動的にドキュメントを書くように動機付ける
ドキュメント作成と開発を一体化する
3. 開発物の品質向上へフィードバックする ドキュメント駆動開発＆フィードバックの形成
4. 今回の成果から構成のスケルトンを作成し再利用 ドキュメントポートフォリオの構築
(´･ω･`)ノ
以上 業務での利用事例でした
仕事でどうやって使ってる？
どうやって職場に広めよう？
コミュニティでの取り組など
質疑応答
