Your SlideShare is downloading. ×
Moving from Publican to Read The Docs
Upcoming SlideShare
Loading in...5

Thanks for flagging this SlideShare!

Oops! An error has occurred.


Introducing the official SlideShare app

Stunning, full-screen experience for iPhone and Android

Text the download link to your phone

Standard text messaging rates apply

Moving from Publican to Read The Docs


Published on

Published in: Technology, News & Politics

1 Like
  • Be the first to comment

No Downloads
Total Views
On Slideshare
From Embeds
Number of Embeds
Embeds 0
No embeds

Report content
Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

No notes for slide


  • 1. Sebastien Goasguen, @sebgoa Going from Publican to Sphinx and RTD
  • 2. IaaS Landscape
  • 3. Going From Publican to ReadTheDocs
  • 4. Insert Presentation Title Here
  • 5. DocBook is great !
  • 6. Publican is a build tool for documentation written in DocBook format “DocBook is a XML schema suited for Books and papers”
  • 7. 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.xml Beginning work on en-US FATAL 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
  • 8. Other issues • Localization / Internationalization / i18n support ( sometimes difficult builds) • Web site hosting • Publican is written in perl • Turn-off for new writers
  • 9. Conversion From Publican to ReadTheDocs
  • 10. Devs love Git/Github
  • 11. 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
  • 12. Life Saver = pandoc $ pandoc --help pandoc [OPTIONS] [FILES] Input formats: native, json, markdown, markdown_strict, markdown_phpextra, markdown_github, markdown_mmd, rst, mediawiki, docbook, textile,html, latex Output 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
  • 13. 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
  • 14. Gotchas • Table of Content headings • Table format • Code snippets • References
  • 15. Build and Host
  • 16. Build for RST projects Sphinx $sphinx-quickstart Drop in your .rst files and build $make html
  • 17. Read The Docs
  • 18. GitHub Integration From Publican to ReadTheDocs
  • 19. Increasing Contributions
  • 20. Seamless integration of RTD with GitHub
  • 21. Activate Service Hooks
  • 22. Drive-By Contributions…
  • 23. i18n
  • 24. README
  • 25. Publican i18n Great support for localization Integrates with Transifex workflow
  • 26. See Marcus’s talk
  • 27. Early Results
  • 28. Conclusions
  • 29. • Easy to contribute to • Looking great • Localization support • Automated build • Remote hosting
  • 30. Almost Done
  • 31. Events CloudStack Collaboration Conference: Vegas, Santa-Clara, Amsterdam Denver April 9-11th Rumors of ApacheCon EU in BUDAPEST !!! Contributing to Apache CloudStack
  • 32. Get Involved with Apache CloudStack Web: Mailing Lists: IRC: 6667 #cloudstack #cloudstack-dev Twitter: @cloudstack LinkedIn: If it didn’t happen on the mailing list, it didn’t happen.