Life with Sphinx 2012 #sphinxconjp

Sphinx-users.jp
Takeshi KOMIYA

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, …

Welcome to SphinxConJP 2012

 This is first Sphinx conference! (maybe)
 7 presentations
 We’ll do Sprint Day tomorrow
 Enjoy Sphinx :-)

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!

Agenda

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

Life with Sphinx 2012 #sphinxconjp

What is Sphinx

 Documentation tool (by Georg Brandl)
 OpenSource (under BSD License)

Characteristic of Sphinx

 Convert TEXT to many formats
 Of course, supports HTML and PDF

Characteristic of Sphinx

 Simple mark-ups
 reST (reSTructured Text)
 like a Wiki notation

=======
Caption
=======

* Item1
* Item2

 TOC tree based documentation

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

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

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.

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

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

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

Topics

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

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

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

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

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

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)

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

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

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!

Future of Sphinx

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

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!)

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

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

Summary

 What is Sphinx
 Sphinx at Present
 Future of Sphinx
 Sphinx Community in Japan
 Next Event
 Sphinx+Translation Hack-a-thon (Oct)

 Enjoy Documentation!

Life with Sphinx 2012 #sphinxconjp

More Related Content

Similar to Life with Sphinx 2012 #sphinxconjp (20)

More from Takeshi Komiya (20)

Recently uploaded (20)

Life with Sphinx 2012 #sphinxconjp