ドキュメントを作りたくなってしまう魔法のツール「Sphinx」

1,607 views

Published on

Published in: Technology
0 Comments
5 Likes
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total views
1,607
On SlideShare
0
From Embeds
0
Number of Embeds
52
Actions
Shares
0
Downloads
7
Comments
0
Likes
5
Embeds 0
No embeds

No notes for slide

ドキュメントを作りたくなってしまう魔法のツール「Sphinx」

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

×