How do I spread reStructuredText and Sphinx to my project team.

1. How to spread
reST and Sphinx
2012-09-16 Sphinx Con JP 2012(#sphinxconjp)
Takanori Suzuki(@takanory)

2. Who am I(お前誰よ)
• 鈴木 たかのり/ Takanori Suzuki
• Twitter: @takanory
• http://takanory.net/
• PyCon JP 2011, 2012 Staff
• Python mini Hack-a-thon(#pyhack)
• Python Bouldering Club(#kabepy)

3. Story
• Motivation
• 1st step: reStructuredText
• 2nd step: Plone + reStructuredText
• 3rd step: Sphinx

4. Motivation
• MS-Word使いたくない / I hate MS-Word
• らくしたい / I hate routine work
• reStructuredTextで書きたい / I like reST

5. reStructuredText

6. reStructuredText
• 1st step
• 議事録を書く / Write minutes
• メールに添付 / Attach to email
• なんとなく読める / Readable

7. reStructuredText

8. reStructuredText
• reStructuredText がなんとなく読める
ようになる / Somehow read
• 同じフォーマットで書く人が出てく
る / Followers come out

9. Plone + reST

10. Plone + reST
• 2nd step
• 議事録を書く / Write minutes
• サイトにアップ / Site upload
• 週報を書く / Write weekly reports
• 相互に書き込み / Collaboration

11. Plone + reST
• Plone
• Python based CMS
• reStructuredText format support

12. Plone + reST

13. Plone + reST

14. Plone + reST
• 普段からreSTを使うようになる /
Everyday use reST
• 楽しく書く / Fun writing
• 他の人を真似する / Imitate others

15. Sphinx

16. Sphinx
• 3rd step
• チームで資料を書く / Team writing
• 書くことに集中 / Focus on writing
• 設定したい人は使えるようにする /
Installation instructions

17. チームでドキュメント
Team writing
• Sphinx のファイル構成を全部作る / I
made document structure
• タイトルと担当者をすべて入れる / I fill
in all titles and all authors
• 目次だけできている状態 / Table of
contents completed

18. 書くことに集中
Focus on writing
• ファイルはバージョン管理 / use Version
Control System
• サーバでbuildしてみんなが読める /
build on Server
• sphinx環境不要 / Do not need sphinx

19. 使えるようにする
Installation instructions
• インストール手順を書く / Installation
document
• conf.py で環境による条件分岐 /
eliminate environment-dependent
• Windows / Linux / Mac
• blockdiag / seqdiag

20. Sphinx
• みんなでドキュメントが作れた !! / We
build specification document !!

21. Summary
• 徐々に広める / little by little spread
• 書くことに集中 / Focus on writing
• 最後は自分で面倒をみる / Take care of
overall

22. Happy writing!