ドキュメンテーションを加速するストレスフリーの作図ツール『blockdiag』 jus2011年6月勉強会

Embed Size (px)

DESCRIPTION

システム開発や保守、運用の現場においてドキュメントは必須のものです。 しかし、ドキュメントの作成・維持には多くのパワーがかかるため、ドキュ メントが存在しない、資料が古いままになっているなどといった現状を多く 耳にします。 本勉強会ではこれらのドキュメントでよく利用される「図」にフォーカスし、 みるみるうちに図を作成できる「blockdiag」をご紹介します。 「blockdiag」はシンプルなテキスト記述からブロック図、ネットワーク図などの 画像ファイルを出力可能なオープンソースの画像生成ツールです。書き やすさ、メンテナンスしやすさを中心にデザインされており、図を作るのに 配置や並べ替えに苦労する必要はありません。 blockdiagのサンプルはこちら このような特徴を持つ「blockdiag」と、シンプルな記述でドキュメントを作成 するツール「Sphinx」を組み合わせることによって、スピーディなドキュメント 作成・維持が可能となります。 本勉強会では「blockdiag」と組み合わせて利用されることの多いドキュメン テーションツール「Sphinx」にも触れつつ以下の構成で紹介します。 - 「blockdiag」とは何か。他のツールとの比較 - 「blockdiag」シリーズの紹介 - 「blockdiag」利用例紹介、デモ - 「blockdiag」と連携するツール Trac, MoinMoin, Sphinx - Sphinxとblockdiagによるドキュメント作成デモ ドキュメント作りが楽しくなると、ソフトウェア開発や運用はきっともっとずっと 楽しくなります。 そしてこの勉強会で、「blockdiag」と「Sphinx」の先に「Webの未来」をきっと 感じることができるでしょう。

Citation preview

  • 1. UNIX 20116Sphinx-users.jp

2. Twitter: @tk0miya () () Sphinx-users.jp Python mini hack-a-thon Sphinx blockdiag Sphinx sphinxcontrib-googlechart rst2pdf () 3. ? document1. 2. 3. (goo ) 4. ? IT 5. 6. ? ? 7. 8. ? 9. ? 10. ? ? 11. Lightweight Documentation 12. Lightweight Documentation 13. Lightweight Documentation Wiki Sphinx blockdiag Javadoc 14. ? Lightweight Documentation 15. blockdiag UML () = Lightweight 16. blockdiag blockdiag seqdiag actdiag nwdiag blockdiag () (GUI ) 17. blockdiag { -> -> ; -> -> ; } 18. blockdiag Enjoy Lightweight Documentation 19. Sphinx Redmine Trac moinmoin Mediawiki Web API 20. Excel, Visio Cacoo astah* PlantUML 21. / 1 22. / . 23. / . 24. / . 25. / . 26. 27. 28. 29. 30. 31. blockdiag blockdiag easy_install Python % easy_install blockdiag % easy_install seqdiag % easy_install actdiag % easy_install nwdiag (http://blockdiag.com/blockdiag-ja/build/html/introduction.html) 32. blockdiag blockdiag % blockdiag sample.diag # sample.png 33. (blockdiag ) blockdiag ->{A -> B -> C;} 34. (blockdiag ) {A [color = red];B [shape = diamond];C [style = dotted];A -> B -> C;} 35. blockdiag (1) / 36. blockdiag (2) () 37. blockdiag (3) shape node1 [shape = roundedbox] 38. blockdiag (4) shape node1 [shape = roundedbox] 39. blockdiag (5) shape node1 [shape = roundedbox] 40. : http://bit.ly/lZkszJ : http://bit.ly/kYpK6Y : http://bit.ly/m7fLsM : http://bit.ly/l6OOhZ 41. (blockdiag ) seqdiag ->=>{// + A => B;// A -> B;} 42. (blockdiag ) { A => B {// B B => C; } } 43. http://bit.ly/lwvEox 44. actdiag nwdiag actdiag: http://bit.ly/kkcgIg nwdiag: http://bit.ly/kR5tYF blockdiag.com 45. blockdiag blockdiag Interactive Shell Web SVG IE Interactive Shell blockdiag 46. Euro Python (6/20-6/26, ) LT () 47. blockdiag Sphinx Trac, Wiki URL: http://blockdiag.com/ Twitter: #blockdiag Google : blockdiag-discuss 48. http://.jp/ @shimizukawa BeProud Django : Sphinx-users.jp Zope/Plone , pyspa, XP : C++/C/8086 -> Python/Rails Python() 49. Python 6/19() : : ATND http://atnd.org/events/16731 PyCon JP 2011 8/27() : : 7 URL: http://2011.pycon.jp/ 50. Sphinx 51. Sphinx 52. Sphinx 53. Sphinx 54. SphinxJUS(2010/12/3) 55. SphinxSphinx+Hack-a-thon(2011/2/12) 56. SphinxJUS(2011/6/18) 57. OSS Python 2.6.2 OpenPNE Web API groonga 58. http://sphinx-users.jp/example.html http://sphinx.pocoo.org/examples.html 59. Sphinx 60. Sphinx 61. Sphinx 62. Sphinx 63. Sphinx 200 http://pygments.org/docs/lexers/ 64. Sphinx 65. Sphinx blockdiag UMLdocxHTML Python 66. Sphinx100% 67. Sphinx100% 68. Word OpenOffice Writer MicrosoftOffice 69. Excel Calc MicrosoftOffice 70. PowerPoint KeyNote OpenOffice Impress 71. Wiki HTML TeX 72. http://www.flickr.com/photos/boothy/26461481/ http://www.flickr.com/photos/omeyamapyonta/3052096CC BY-NC by Dr Snafu093/ CC BY-SA by PYONKOWord Excel Wiki Sphinxhttp://www.flickr.com/photos/johncarleton/2367673332/ http://www.flickr.com/photos/stompy/11300916/ CC BY-CC BY-NC-SA by John CarletonNC by Abizern 73. Word - proshttp://www.flickr.com/photos/jetalone/861945664/CC BY by jetalone 74. Word - pros etchttp://www.flickr.com/photos/jetalone/861945664/CC BY by jetalone 75. Word - conshttp://www.flickr.com/photos/jetalone/861945664/CC BY by jetalone 76. Word - cons 1 http://www.flickr.com/photos/jetalone/861945664/CC BY by jetalone 77. Excel - pros http://www.flickr.com/photos/21183810@N00/43665 18191/ CC BY-NC-SA by Jerome Rothermund 78. Excel - pros Excel http://www.flickr.com/photos/21183810@N00/43665 18191/ CC BY-NC-SA by Jerome Rothermund 79. Excel - cons http://www.flickr.com/photos/21183810@N00/43665 18191/ CC BY-NC-SA by Jerome Rothermund 80. Excel - cons http://www.flickr.com/photos/21183810@N00/43665 18191/ CC BY-NC-SA by Jerome Rothermund 81. Wiki - proshttp://www.flickr.com/photos/7506006@N07/1197395511/ CC BY-NC-ND by milky.way 82. Wiki - pros http://www.flickr.com/photos/7506006@N07/1197395511/ CC BY-NC-ND by milky.way 83. Wiki - conshttp://www.flickr.com/photos/7506006@N07/1197395511/ CC BY-NC-ND by milky.way 84. Wiki - cons Wikipedia http://www.flickr.com/photos/7506006@N07/1197395511/ CC BY-NC-ND by milky.way 85. Sphinx - proshttp://www.flickr.com/photos/18261299@N00/4472408386/ CC BY-SA by sweet_redbird 86. Sphinx - pros OKhttp://www.flickr.com/photos/18261299@N00/4472408386/ CC BY-SA by sweet_redbird 87. Sphinx - conshttp://www.flickr.com/photos/18261299@N00/4472408386/ CC BY-SA by sweet_redbird 88. Sphinx - cons WYSIWIGhttp://www.flickr.com/photos/18261299@N00/4472408386/ CC BY-SA by sweet_redbird 89. Sphinx(Linux, MacOS X) Python, easy_install, Sphinx3 Ubuntu$ sudo apt-get install python-sphinx Mac OS X$ sudo port install python-sphinx 90. Sphinx(Windows) Python, easy_install, Sphinx3 Pythonpython-2.7.2.msi easy_install (distribute_setup.py) C:> python distribute_setup.py SphinxC:> easy_install sphinxDemo 91. Sphinx(Windows) Sphinx Sphinx-1.0.7.20110618-py2.7-win32.exe blockdiagDemo 92. Sphinx : docx : blockdiag HTML: 93. Sphinx autodoc docstring intersphinx Sphinx pngmath PNG jsmath JavaScript graphviz Graphviz coverage todo TodoSphinx 94. Sphinx blockdiag sdedit UML sphinxjp.themes HTML docxbuilder SphinxWord 95. blockdiag by @tk0miya sphinxcontrib-blockdiag Sphinx .. blockdiag:: diagram webapp { login -> something -> logout -> login } 96. 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() Java 97. sphinxjp.themes by @shimizukawasphinx-users.jp(s6) 98. docxbuilder by @shimizukawa SphinxWord 99. Sphinx sphinx-quickstart$ mkdir Unix-How-to$ cd Unix-How-to$ sphinx-quickstart Enter Makefile _build conf.py _static _templates 3 conf.py index.rst make.bat Demo 100. reST reST = reStructuredText http://sphinx-users.jp/doc10/rest.htmlDemo============ ============ ========= --------------1 toctree-2 #. 1 #. 2 101. Sphinx Makefile$ make htmlDemo============ ============ =========1 2-1 1. 1-2 2. 2 #. 1 #. 2 102. (1/2) HTMLLaTeXPDF ePub $ make latex $ make latexpdf $ make epub HTML Demo 103. (2/2) blockdiag ()C:> easy_install sphinxcontrib-blockdiag Demo conf.py extensions = [] extensions.append(sphinxcontrib.blockdiag) blockdiag_fontpath = rC:WindowsFontsmsgothic.ttc .. blockdiag::{ A -> B -> C; } 104. Jinja2 2html : layout.html : page.html basic 105. Sphinx Sphinx Python&(Erlang, Ruby, C++, JavaScript) ) C.. c:function:: int printf(const char *format, ) 106. SphinxSphinx 107. Sphinx1/21/6463/6411Sphinx 108. Sphinx Word 109. Sphinx Word Sphinx 110. SphinxPowerPoint 111. Sphinx 112. (@r_rudi) http://sphinx-users.jp/ 113. Sphinx 114. Sphinx Web: http://sphinx-users.jp/ : http://sphinx-users.jp/mailinglist.html : http://sphinx-users.jp/event/ Twitter: #sphinxjp