Life with Sphinx 2012 #sphinxconjp

2,075 views

Published on

Published in: Technology
  • Be the first to comment

Life with Sphinx 2012 #sphinxconjp

  1. 1. Sphinx-users.jpTakeshi KOMIYA
  2. 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. 3. Welcome to SphinxConJP 2012 This is first Sphinx conference! (maybe)  7 presentations  We’ll do Sprint Day tomorrow Enjoy Sphinx :-)
  4. 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. 5. Sphinx-users.jpTakeshi KOMIYA
  6. 6. Agenda1. What is Sphinx2. Sphinx at Present3. Future of Sphinx4. Sphinx community in Japan5. Summary
  7. 7. What is Sphinx Documentation tool (by Georg Brandl) OpenSource (under BSD License)
  8. 8. Characteristic of Sphinx Convert TEXT to many formats  Of course, supports HTML and PDF
  9. 9. Characteristic of Sphinx
  10. 10. Characteristic of Sphinx Simple mark-ups  reST (reSTructured Text)  like a Wiki notation ======= Caption ======= * Item1 * Item2 TOC tree based documentation
  11. 11. 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
  12. 12. 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
  13. 13. 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.
  14. 14. 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
  15. 15. 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
  16. 16. 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
  17. 17. Topics Updating Sphinx-users.jp website Appearance of readthedocs.org Patch for Japanese PDF conversion Increasing Sphinx extensions Increasing Sphinx themes Increasing Usecases
  18. 18. 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
  19. 19. 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
  20. 20. 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
  21. 21. 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
  22. 22. 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)
  23. 23. 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
  24. 24. 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
  25. 25. 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!
  26. 26. Future of Sphinx This SphinxCon is first step to future Themes of presentations in this conference  Extensions  Themes  Automation  Use cases  Web editor
  27. 27. 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!)
  28. 28. 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
  29. 29. 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
  30. 30. Summary What is Sphinx Sphinx at Present Future of Sphinx Sphinx Community in Japan Next Event  Sphinx+Translation Hack-a-thon (Oct) Enjoy Documentation!

×