Sebastien Goasguen,
@sebgoa
Going from Publican to Sphinx and RTD
IaaS Landscape
Going From Publican to ReadTheDocs
Insert Presentation Title Here
DocBook is great !
Publican is a build tool for documentation written in DocBook format
“DocBook is a XML schema suited for Books and papers”
But has issues…
540 DocBook files
43173 lines of XML
Processing file tmp/en-US/xml_tmp/xenserver-topology-req.xml -> tmp/en-US/xml/xenserver-topology-req.xml
Processing file tmp/en-US/xml_tmp/zone-add.xml -> tmp/en-US/xml/zone-add.xmlBeginning work on en-USFATAL ERROR: XInclude:1604 in secondary-storage-add.xml on line 227: could not load s3-ss-add.xml, and no fallback was found at /opt/local/libexec/perl5.12/sitebin/publican line 895
Other issues
• Localization / Internationalization / i18n support ( sometimes difficult builds)
• Web site hosting
• Publican is written in perl
• Turn-off for new writers
Drag picture to placeholder or click icon to add
Conversion
From Publican to ReadTheDocs
Devs love Git/Github
Back to basics
“reStructuredText is an easy-to-read, what-you-see-is-what-you-get plaintext markup syntax and parser system”
…and I write Python
Life Saver = pandoc$ pandoc --helppandoc [OPTIONS] [FILES]Input formats: native, json, markdown, markdown_strict, markdown_phpextra, markdown_github, markdown_mmd, rst, mediawiki, docbook,
textile,html, latexOutput formats: native, json, docx, odt, epub, epub3, fb2, html, html5, s5, slidy, slideous, dzslides, docbook, opendocument, latex,
beamer,context, texinfo, man, markdown, markdown_strict, markdown_phpextra, markdown_github, markdown_mmd, plain,rst,mediawiki, textile, rtf, org, asciidoc
Options: -f FORMAT, -r FORMAT --from=FORMAT, --read=FORMAT -t FORMAT, -w FORMAT --to=FORMAT, --write=FORMAT -o FILENAME --output=FILENAME --data-dir=DIRECTORY
HTML to RST
Publican build:
$ publican build --formats=html-single --langs=en-US --config=publican-installation.cfg
$ pandoc –f html –t rst –o guide.rst guide.html
Gotchas
• Table of Content headings
• Table format
• Code snippets
• References
Drag picture to placeholder or click icon to add
Build and Host
Build for RST projects
Sphinx
$sphinx-quickstart
Drop in your .rst files and build
$make html
Read The Docs
Drag picture to placeholder or click icon to add
GitHub Integration
From Publican to ReadTheDocs
Increasing Contributions
Seamless integration of RTD with GitHub
Activate Service Hooks
Drive-By Contributions…
Drag picture to placeholder or click icon to add
i18n
README
Publican i18n
Great support for localization
Integrates with Transifex workflow
See Marcus’s talk
Early Results
Drag picture to placeholder or click icon to add
Conclusions
• Easy to contribute to • Looking great• Localization support• Automated build• Remote hosting
Drag picture to placeholder or click icon to add
Almost Done
EventsCloudStack Collaboration Conference:
Vegas, Santa-Clara, Amsterdam
Denver April 9-11th
Rumors of ApacheCon EU in BUDAPEST !!!
Contributing to Apache CloudStack
Get Involved with Apache CloudStack
Web: http://cloudstack.apache.org/
Mailing Lists: cloudstack.apache.org/mailing-lists.html
IRC: irc.freenode.net: 6667 #cloudstack #cloudstack-dev
Twitter: @cloudstack
LinkedIn: www.linkedin.com/groups/CloudStack-Users-Group-3144859
If it didn’t happen on the mailing list, it didn’t happen.