life with sphinx 2012 #sphinxconjp

Life with Sphinxin 2012

Sphinx-users.jpTakeshi KOMIYA

Who am I ?

Works at Time Intermedia Corp.Communities:

Sphinx-users.jpPython mini hack-a-thon

Making some documentation toolsBlockdiag familySphinx extensions

googlechart, googlemaps, …

Twitter: @tk0miya

Welcome to SphinxConJP 2012

This is first Sphinx conference! (maybe)7 presentationsWe’ll do Sprint Day tomorrow

Enjoy Sphinx :-)

Question

Do you use Sphinx?1. don’t know about Sphinx2. I know, but had not use yet3. Installed, but not use yet4. Off course using!

Life with Sphinxin 2012

Sphinx-users.jpTakeshi KOMIYA

Agenda

1. What is Sphinx2. Sphinx at Present3. Future of Sphinx4. Sphinx community in Japan5. Summary

1.What is Sphinx

What is Sphinx

Documentation tool (by Georg Brandl)

OpenSource (under BSD License)

Characteristic of Sphinx

Convert TEXT to many formatsOf course, supports HTML and PDF

Characteristic of Sphinx

Characteristic of Sphinx

Simple mark-upsreST (reSTructured Text)like a Wiki notation

TOC tree based documentation

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

* Item1* Item2

Better in Sphinx

Text file (reST) as INPUTUse any editors and ENVs as you likeAll you can use VCSAuto generation docs using tools

Ex. schema2rst (DB definition)Extensible

Sphinx ext. and themesBetter than other tools

Worth in Sphinx

Have to convert in anytimeWrite, make, write, make…Need some utilities if you want

automationreST can represent only meanings

Does not support layoutingex. align, columns layout

Could not write graphs and figuresOffice suite uses hate this behavior :-p

Main usage of Sphinx

Development docsOSS docs (Ex. Python)Design docs, references

Web SiteBlogs, Corporate site

PublishingExpert 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

2.Sphinx at Present

Topics

Updating Sphinx-users.jp websiteAppearance of readthedocs.orgPatch for Japanese PDF conversionIncreasing Sphinx extensionsIncreasing Sphinx themesIncreasing Usecases

Updating Sphinx-users.jp website

http://sphinx-users.jp/Contents for beginersTips

PDF conversions, themes, etc.Introduce of ext.

Rev. lookup dict.Event Info

Appearance of readthedocs.org

Hosting service for Sphinx docsbuild and publish automaticallypush sources to github/bitbucket/etc

ONLYVery easy to publish docs

Patch for Japanese PDF

At once, PDF conversion is a hard to Japanese docs

Mr.Uchida works for problem1. Apply patch to Sphinx2. Install TeXLive (>= 2011)3. Edit conf.py4. Run `make latexpdfja’

He send pull-request, and we are waiting

More details, visit sphins-users.jp Now

Increasing Sphinx extensions

Embedding many mediaYoutube, Slideshare, Google Maps

Writing figuresblockdiag, seqdiag, plantuml

Supporting writing reSTwikitable, japanesesupport

etc.adding theme, adding HTML styles

Increasing Sphinx themes

theme.core ext. make themes pluggable

Themes for presentationsS6 (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 OSSPython, frameworks and librariesUsed outside of Python

Symphony2, CakePHPSome campanies start using Sphinx

Share docs as HTML in teamDelivery docs as PDF to customers

Somebody uses to their official website

3.Future of Sphinx

Future of Sphinx

Merging “Japanese PDF support” patchBe able to generate PDF with no patchesAppeal to upstream

AutomationWe needs more tips (cf. Jenkins)

Theme for PDFWant to custom style of PDFBe able to change without TeX

knowledges

Future of Sphinx

Increase themes and extensions moreStill hard to edit figuresgives more choices to anyone

Web editor for SphinxEditing docs using web browser ONLYEasy to start editting (like Wiki)

UsecasesWe want to use in our work!

Future of Sphinx

This SphinxCon is first step to futureThemes of presentations in this

conferenceExtensionsThemesAutomationUse casesWeb editor

4.Sphinx Community in Japan

Sphinx-users.jp

Sphinx community in JapanMailing listTwitter (#sphinxjp)

Updating website and translated docsEvents

Sphinx+Translation Hack-a-thon (Tokyo)Sphinx Morning-meetup (Osaka)Sphinx Hands-onSphinxCon JP 2012 (Here!)

If you met problems in Sphinx…

Ask for Sphinx-users.jpTwitter, ML, Event, anyway ok

Ask questionsAnswer to questionsShare your ideas and tips

Next Events

SphinxCon Sprintin 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 breaksWe open hack-a-thon almost every month

5.Summary

Summary

What is SphinxSphinx at PresentFuture of SphinxSphinx Community in JapanNext Event

Sphinx+Translation Hack-a-thon (Oct)

Enjoy Documentation!