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