1. Sphinx-users.jp
Takeshi KOMIYA

2. Who am I ?
Twitter: @tk0miya
 Works at Time Intermedia Corp.
 Communities:
 Sphinx-users.jp
 Python mini hack-a-thon
 Making some documentation tools
 Blockdiag family
 Sphinx extensions
 googlechart, googlemaps, …

3. Welcome to SphinxConJP 2012
 This is first Sphinx conference! (maybe)
 7 presentations
 We’ll do Sprint Day tomorrow
 Enjoy Sphinx :-)

4. Question
 Do you use Sphinx?
1. don’t know about Sphinx
2. I know, but had not use yet
3. Installed, but not use yet
4. Off course using!

5. Sphinx-users.jp
Takeshi KOMIYA

6. Agenda
1. What is Sphinx
2. Sphinx at Present
3. Future of Sphinx
4. Sphinx community in Japan
5. Summary

8. What is Sphinx
 Documentation tool (by Georg Brandl)
 OpenSource (under BSD License)

9. Characteristic of Sphinx
 Convert TEXT to many formats
 Of course, supports HTML and PDF

10. Characteristic of Sphinx

11. Characteristic of Sphinx
 Simple mark-ups
 reST (reSTructured Text)
 like a Wiki notation
=======
Caption
=======
* Item1
* Item2
 TOC tree based documentation

12. Better in Sphinx
 Text file (reST) as INPUT
 Use any editors and ENVs as you like
 All you can use VCS
 Auto generation docs using tools
 Ex. schema2rst (DB definition)
 Extensible
 Sphinx ext. and themes
 Better than other tools

13. Worth in Sphinx
 Have to convert in anytime
 Write, make, write, make…
 Need some utilities if you want automation
 reST can represent only meanings
 Does not support layouting
 ex. align, columns layout
 Could not write graphs and figures
 Office suite uses hate this behavior :-p

14. Main usage of Sphinx
 Development docs
 OSS docs (Ex. Python)
 Design docs, references
 Web Site
 Blogs, Corporate site
 Publishing
 Expert Python Programing (ja)
 Python Professional Programming (ja)
 etc.

15. Comparation
 MS-Word
 ◯ supports layout (vertical, column layout)
 ◯ gives Spell/Syntax Checker
 ◯ has usable update-history manager
 ◯ easy to write graphs and figures
 ✕ hard to restructure docs
 ✕ hard to write by many people
 ✕ have to install Office suit

16. Comparation
 MS-Excel
 ◯ everybody can use. de fact standard in JP.
 ◯ easy to write graphs and figures
 ✕ No doc-structures
 ✕ very Hard to edit graphs and figures…
 ✕ Inprintable or hard to print
 ✕ have to install Office suit

17. Comparation
 Wiki
 ◯ use only web browsers on writing
 ◯ simple notation
 ✕ could not write graphs and figures
 ✕ be lost in semi-lattice documents
 ✕ hard to change layout of docs

19. Topics
 Updating Sphinx-users.jp website
 Appearance of readthedocs.org
 Patch for Japanese PDF conversion
 Increasing Sphinx extensions
 Increasing Sphinx themes
 Increasing Usecases

20. Updating Sphinx-users.jp website
 http://sphinx-users.jp/
 Contents for beginers
 Tips
 PDF conversions, themes, etc.
 Introduce of ext.
 Rev. lookup dict.
 Event Info

21. Appearance of readthedocs.org
 Hosting service for Sphinx docs
 build and publish automatically
 push sources to github/bitbucket/etc ONLY
 Very easy to publish docs

22. Patch for Japanese PDF
 At once, PDF conversion is a hard to
Japanese docs
 Mr.Uchida works for problem
1. Apply patch to Sphinx
2. Install TeXLive (>= 2011)
3. Edit conf.py
4. Run `make latexpdfja’
 He send pull-request, and we are waiting
 More details, visit sphins-users.jp Now

23. Increasing Sphinx extensions
 Embedding many media
 Youtube, Slideshare, Google Maps
 Writing figures
 blockdiag, seqdiag, plantuml
 Supporting writing reST
 wikitable, japanesesupport
 etc.
 adding theme, adding HTML styles

24. Increasing Sphinx themes
 theme.core ext. make themes pluggable
 Themes for presentations
 S6 (sphinxjp.themes.s6)
 htmlslide (sphinxjp.themes.htmlslide)
 impressjs (sphinxjp.themes.impressjs)
 Cool themes
 bizstyle (sphinxjp.themes.bizstyle)
 Solarized (sphinxjp.themes.solarized)

25. Increasing Usecases
 Increasing Use case of OSS
 Python, frameworks and libraries
 Used outside of Python
 Symphony2, CakePHP
 Some campanies start using Sphinx
 Share docs as HTML in team
 Delivery docs as PDF to customers
 Somebody uses to their official website

27. Future of Sphinx
 Merging “Japanese PDF support” patch
 Be able to generate PDF with no patches
 Appeal to upstream
 Automation
 We needs more tips (cf. Jenkins)
 Theme for PDF
 Want to custom style of PDF
 Be able to change without TeX knowledges

28. Future of Sphinx
 Increase themes and extensions more
 Still hard to edit figures
 gives more choices to anyone
 Web editor for Sphinx
 Editing docs using web browser ONLY
 Easy to start editting (like Wiki)
 Usecases
 We want to use in our work!

29. Future of Sphinx
 This SphinxCon is first step to future
 Themes of presentations in this conference
 Extensions
 Themes
 Automation
 Use cases
 Web editor

31. Sphinx-users.jp
 Sphinx community in Japan
 Mailing list
 Twitter (#sphinxjp)
 Updating website and translated docs
 Events
 Sphinx+Translation Hack-a-thon (Tokyo)
 Sphinx Morning-meetup (Osaka)
 Sphinx Hands-on
 SphinxCon JP 2012 (Here!)

32. If you met problems in Sphinx…
 Ask for Sphinx-users.jp
 Twitter, ML, Event, anyway ok
 Ask questions
 Answer to questions
 Share your ideas and tips

33. Next Events
 SphinxCon Sprint
 in PyCon Sprint (Tomorrow)
 Hands-on or Sprint
 Sphinx+Translation Hack-a-thon (Oct)
 10/13(Sat) at TimeIntermedia (Tokyo)
 Event page is on http://connpass.com/
 Hack-a-thon and Tea breaks
 We open hack-a-thon almost every month

35. Summary
 What is Sphinx
 Sphinx at Present
 Future of Sphinx
 Sphinx Community in Japan
 Next Event
 Sphinx+Translation Hack-a-thon (Oct)
 Enjoy Documentation!