This document summarizes a presentation about the Sphinx documentation tool. It discusses what Sphinx is, how it is currently being used, ideas for its future development, the Sphinx community in Japan, and announces an upcoming Sphinx hackathon event. The presentation covers topics like Sphinx extensions, themes, automation, usage cases, and the future inclusion of improved Japanese PDF support and a web-based editor.

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!