![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()](https://image.slidesharecdn.com/jussphinx-101208032606-phpapp02/85/Sphinx-21-320.jpg)
ドキュメントを作りたくなってしまう魔法のツール「Sphinx」
- 1. Sphinx-‐users.jp 渋川よしき、山口能迪、清水川貴之 日本UNIXユーザ会 2010年12月勉強会
- 2. 自己紹介 山口能迪（やまぐちよしふみ） id : ymotongpoo 「とんぷー」と呼んでください OSSのドキュメント翻訳をしています Tornado （軽量Webフレームワーク） Redis （高機能KVS） Jinja2 （テンプレートエンジン） など
- 3. 自己紹介：渋川よしき 仕事 大手製造業の社内SE 社外で技術習得して社内で楽をする 参加コミュニティ SphinxUsers.jp会長 翻訳ハッカソンとかを継続開催予定 日本XPユーザグループ代表 とちぎRuby Python温泉(系) 11/14にPython Hack-‐a-‐thon 今年出した本 IT業界を楽しく生き抜くための つまみぐい勉強法(技術評論社) エキスパートPythonプログラミング (アスキーメディアワークス 電子出版文書フォーマット技術動向調 査(インプレスR&D) Twitter: @shibukawa 写真: 清水川webより転載
- 4. 自己紹介： 清水川 貴之 http://清水川.jp/ @shimizukawa オープンソースコミュニティー活動: Sphinx-‐users.jp 副会長 Zope/Plone 運営 その他, pyspa系, XP系 言語: Python, Rails, 昔はC++/C/8086 仕事: フリーでPython/Railsやってます 翻訳本 エキスパートPythonプログラミング アスキー・メディアワークス B5変 416ページ
- 7. 拡張機能で、機能を追加していくことができる ドキュメントは100%日本語化されている sphinx-‐user.jp 強力なコードハイライト 利用実績多数！ 国内： http://sphinx-‐users.jp/example.html 国外： http://sphinx.pocoo.org/examples.html
- 9. お品書き デモ 1. Sphinxのインストール 2. Sphinxプロジェクトの作成 3. reSTによるドキュメント作成 4. Sphinxによるドキュメントのビルド 応用例（ビルド、テンプレート） サイト 拡張について
- 10. 1/4 Sphinxのインストール 2分で始めましょう！ 必要なもの Python, easy_install, Sphinxの3点セット パッケージ管理ツールを使えば一瞬 Ubuntu Mac OS X 準備完了です $ sudo apt-‐get install python-‐sphinx $ sudo port install python-‐sphinx
- 11. 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
- 12. 3/4 reSTによるドキュメント作成 reST = reStructuredText http://sphinx-‐users.jp/doc10/rest.html テキストでも見やすい形 見出し コードブロック（ハイライト付き） 文書内／文書外リンク 表 toctreeなどを作成する ============ 大見出し ============ 中見出し ========= 小見出し -‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐-‐ -‐ リストアイテム1 -‐ リストアイテム2 #. 自動採番アイテム1 #. 自動採番アイテム2 Demo
- 13. 4/4 Sphinxによるドキュメントのビルド 自動作成されたMakefileをそのまま利用するだけ ============ 大見出し ============ 見出し ========= -‐ リストアイテム1 -‐ リストアイテム2 #. 自動採番アイテム1 #. 自動採番アイテム2 大見出し 中見出し ・リストアイテム1 ・リストアイテム2 1. 自動採番アイテム1 2. 自動採番アイテム2 $ make html Demo
- 14. 応用例 1/2 HTML以外にもデフォルトでLaTeX、PDF 、ePubに HTMLもデフォルトで複数のテーマを使用可 $ make latex $ make latexpdf $ make epub Demo
- 15. テンプレートの作成 テンプレートエンジン “Jinja2”を利用している 大まかに分けて2つのhtmlを作成する ドキュメント全体の基礎 : layout.html 各ページ : page.html デフォルトテーマ basic のテンプレート継承により 時間が削減 自分でテンプレートを作成することも可能
- 16. Sphinx実用例 多くのOSSドキュメントやサイトで採用実績あり Python 2.6.2ドキュメント OpenPNE Web API仕様書 groongaドキュメント…他多数 テンプレート機能を用いてサイトを構成
- 17. Sphinxドメイン ある言語を説明するマークアップとSphinx内のオブ ジェクトのリンク Python以外にも多くの言語に対応&独自に作成可能 (Erlang, Ruby, C++, JavaScript…) ドキュメント内で相互参照が可能 例) C .. c:function:: int printf(const char *format, …)
- 18. Sphinx拡張 拡張をすることで様々な要求に対応できる 新たな出力形式に対応したい マークアップを拡張したい Sphinx拡張とは言うものの デフォルトで組み込まれている拡張が多数！
- 19. 組み込みのSphinx拡張 autodoc – docstring からの読み込み intersphinx – 他のSphinxドキュメントへのリンク pngmath – 数式をPNG画像にレンダリング jsmath – JavaScriptを用いて数式をレンダリング graphviz – Graphvizのグラフを追加 coverage – ドキュメントのカバレッジ状況の収集 todo – Todoアイテムのサポート 他にも多くの組み込みSphinx拡張あり
- 20. サードパーティのSphinx拡張 その他特筆すべき拡張 sdedit UMLを描けます！ blockdiag ブロック遷移図を簡単な記述だけで作成 docx SphinxでWordファイルを作成
- 21. 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()
- 22. blockdiag by @tk0miya ブロック遷移図を文字のみで書けます sphinxcontrib-‐blockdiag でSphinxでブロック遷移図 を書くことが可能 .. blockdiag:: diagram webapp { login -‐> something -‐> logout -‐> login }
- 23. docx SphinxからWord形式で出力する拡張 現在誠意開発中 by 清水川さん
- 24. まとめ Sphinxは インストールが簡単 設定も簡単 書くのも簡単 ビルドも簡単 カスタマイズも簡単 拡張もできる サイトも作れる という素晴らしいドキュメントツールだった！
- 26. ドキュメントを書くのに、何を使用しています か？ ワープロソフト Word 一太郎 OpenOffice Writer MicrosoftのOfficeの テンプレートのサイトより転載
- 27. ドキュメントを書くのに、何を使用しています か？ 表計算 Excel Calc MicrosoftのOfficeの テンプレートのサイトより転載
- 28. ドキュメントを書くのに、何を使用しています か？ プレゼンテーション PowerPoint KeyNote OpenOffice Impress
- 29. ドキュメントを書くのに、何を使用しています か？ それ以外 Wiki HTML手書き TeX
- 30. 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
- 31. Word -‐ pros 縦書きで編集できる 文法チェックしてくれる 差分比較機能がある 参考文献、索引、 差し込み印刷etc… http://www.flickr.com/photos/jetalone/861945664/ CC BY by jetalone
- 32. Word -‐ cons 巨大な1ファイルになる 探すのが大変 複数人で編集が大変 章の入れ替えとか厳しい http://www.flickr.com/photos/jetalone/861945664/ CC BY by jetalone
- 33. Excel -‐ pros Excel扱える人は多い ぱっと作るのは早くできる ロジカルシンキング的に苦心しなくても、罫線で武 装すると、見た目が立派に見える http://www.flickr.com/photos/ 21183810@N00/4366518191/ CC BY-‐NC-‐SA by Jerome Rothermund
- 34. Excel -‐ cons ワークシートで分断され、閲覧性が悪い 内容の追加でレイアウトの修正が必要になると、修 正に膨大な時間がかかる http://www.flickr.com/photos/ 21183810@N00/4366518191/ CC BY-‐NC-‐SA by Jerome Rothermund
- 35. Wiki -‐ pros 圧倒的に柔軟 構造化されていなくても、とりあえず入れておける 複数人での編集・閲覧ができる http://www.flickr.com/photos/ 7506006@N07/1197395511/ CC BY-‐NC-‐ND by milky.way
- 36. Wiki -‐ cons 文章の構成、質の維持に目を光らせる必要がある あるいは、Wikipediaのように構成を決めておく 全体の構成を修正するのに手間がかかる トップダウン型ではないので、まとめて印刷や他形 式に変換がやりにくい http://www.flickr.com/photos/ 7506006@N07/1197395511/ CC BY-‐NC-‐ND by milky.way
- 37. Sphinx -‐ pros ドキュメントの背骨がしっかりさせる 有機的に文章を繋げる仕組みを持っている 説明ユニット プレーンテキスト。バージョンコントロールOK！ http://www.flickr.com/photos/ 18261299@N00/4472408386/ CC BY-‐SA by sweet_redbird
- 38. Sphinx -‐ cons 背骨を気にして、コンテンツを追加する必要 マークアップを覚える WYSIWIGではない http://www.flickr.com/photos/ 18261299@N00/4472408386/ CC BY-‐SA by sweet_redbird
- 40. 成長のポイント 背骨 toctree！toctree！toctree！ 神経のネットワーク セマンティックスを定義していく
- 41. 背骨の肝：セクションタイトル ドキュメントを構成する重要な要素 #, *, =, -‐, ^, ~, “などの記号で下だけ、上下を囲う 自分なりのルールを決めておくと良い 単体のソース内の登場順でH1, H2, H3..が決まる 文字長よりも短いと警告が出ます ======== はじめに ======== 想定読者 ======== 新人社会人 ---------- はじめに 想定読者 新人社会人
- 42. 背骨の肝：親子関係の定義 Sphinxの一番重要な部分 toctreeディレクティブを使って定義する 拡張子なしのファイル名を列挙する 目次がその場で作られる .. toctree:: :maxdepth: 2 preface overview/index defensive/index はじめに 本書の考えるゴール 本書を作るにあたって 本書で説明していくこと つまみぐい勉強法 勉強はつまみぐいから 大切なことは、継続 自分に合うものを選ぼう 終着点は自分で決めよう
- 43. 背骨の肝：親子関係の定義 セクションタイトルを子供の文書から引っ張ってき て目次を作る toctree自体は1文書に何個も書ける toctree表示位置に、子供の文書のセクション構造が 挿入される toctreeができたら、Sphinx黒帯！
- 44. どこからどう書いていく？
- 46. 神経ネットワーク 巨大なソフトウェアをどう作る？ • モジュール化 • 単独のプログラム+シェル(UNIX的アプローチ) • 公開インタフェースによるアクセス(粗結合) • メタプログラミング
- 48. セマンティック 定義(説明ユニット)とそこへのリンク ソースコードの構成要素の説明とリンク .. module:: berrymq .. function:: talk(識別子) メッセージを送ります クライアントとコネクションを張っ たら :func:`talk` が使えるように なります berrymq.talk(識別子)! メッセージを送ります" クライアントとコネクションを張っ たら talk() が使えるようになり ます ディレクティブ ロール .. _名前: :ref:`名前` .. function:: 名前 :func:`名前` .. method:: 名前 :meth:`名前` ディレクティブ ロール .. module:: 名前 :mod:`名前` .. class:: 名前 :class:`名前` .. attr:: 名前 :attr:`名前`
- 49. ドキュメントのモチベーションを上げ いろんなやる気のスイッチを活用 全体像を見て、足りない項目を補完 とにかく、細かい部分から徹底的に丁寧に 索引を見て、索引を充実させる 読む人ごとの入り口を作ってみる いろんなフォーマットで出力してみる
- 50. 対象 • ソフトウェア開発プロジェクト • 規模：１名∼１０名前後
- 53. ドキュメントが書けない開発現場 なぜドキュメントを書けないの？ どこに書いて良いか分からない 何を書いて良いか分からない どう書いて良いか分からない どんなツールを使えばいいか分からない どこに置けばいいか分からない どうせドキュメントなんて誰も見ない ドキュメントはあとで書けばいい ドキュメントを書く時間がない めんどくさい 楽しくない
- 54. ω･`) ・・・
- 56. 問題と対策 ドキュメント作成をさぼってしま う原因 原因を取り除いてしまおう どういう構成で書いたら良いか 分からない 自分は文章を書くのが苦手だ 誰も見ない文章は書きたくない 開発終了に向かうにつれて時間 がなくなる プロジェクト開始時に構成 を整備しておく 書き方の指針を決めておく 能動的にドキュメントを書 くよう動機づける 先にドキュメントを書くよ うにする 簡単！ 面倒..
- 57. ゴール 1. ドキュメントを簡単に書けるようにする 2. みんなが能動的にドキュメントを書くよう に 動機付ける 3. 開発物の品質向上へフィードバックする 4. 今回の成果から構成のスケルトンを作成し 再利用する
- 60. 書き方のルールを決めておく 「技術文書を書くための7つのルール」を押さえてお こう！ 1. ２つのステップで書く 2. 読者のターゲットを明確にする 3. シンプルなスタイルを使用する 4. 情報のスコープを絞る 5. 実在するようなコードのサンプルを使用する 6. なるべく少なく、かつ十分なドキュメント 7. テンプレートの使用 「エキスパートPythonプログラミング」 10章 （アスキーメディアワークス刊）より抜粋 10章: プロジェクトのドキュメント作成 （無料公開中）
- 61. 読者ターゲット別に大きく分ける 誰が読むべきものかを意識して構成を作る。 例えば以下のように構成。 マネージャ向け 設計者向け 開発者向け 運用者向け APPENDIX
- 62. ドキュメントを書くための手間を減らす 開始時に分かっている共有情報を 予め書いておく 数ステップでドキュメントを書く環境を 整えられるようにする 共有や閲覧の仕組みを自動化して 開発プロセスに組み込む
- 66. Step3 既に分かっている情報を追加 マネージャー、設計者、開発者それぞれに必要とな る、 プロジェクト特有の情報を記載
- 72. 繋がりを加速する 自動化のすゝめ
- 73. ドキュメント作成を開発サイクルに組み込む 継続的インテグレー ション 課題管理 環境構築 リポジトリ 自動テスト 環境構築 自動テスト 本番環境 環境構築 ドキュメン ト 生成 ドキュメント 生成 実装 ドキュメンテーション XP祭り2010 資料より抜粋 Pythonで アジャイル開発サイクル 2010ver. http://清水川.jp/docs/xpfest2010/
- 75. 次の開発のために ドキュメントポートフォリオへ の昇華 「エキスパートPythonプログラミング」 10章 （アスキーメディアワークス刊）より抜粋 10章: プロジェクトのドキュメント作成 （無料公開中）
- 76. まとめ 1. ドキュメントを簡単に書けるようにする ７つのルールと構成のテンプレート化 2. みんなが能動的にドキュメントを書くように動機 付ける ドキュメント作成と開発を一体化する 3. 開発物の品質向上へフィードバックする ドキュメント駆動開発＆フィードバックの形成 4. 今回の成果から構成のスケルトンを作成し再利用 ドキュメントポートフォリオの構築