Moving from Publican to Read The Docs

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.