Moving from Publican to Read The Docs
•Download as PPTX, PDF•
2 likes•3,181 views
This document summarizes a presentation about transitioning documentation from Publican to Sphinx and hosting it on ReadTheDocs. It discusses some issues with Publican like localization support and web hosting. It then covers converting the DocBook files to reStructuredText using pandoc and hosting the documentation on ReadTheDocs, which integrates seamlessly with GitHub. The results have been easy contribution and an automated build/hosting process with good localization support.
Report
Share
Moving from Publican to Read The Docs
- 1. Sebastien Goasguen, @sebgoa Going from Publican to Sphinx and RTD
- 4. Going From Publican to ReadTheDocs
- 6. Insert Presentation Title Here
- 8. Publican is a build tool for documentation written in DocBook format “DocBook is a XML schema suited for Books and papers”
- 9. 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
- 12. Other issues • Localization / Internationalization / i18n support ( sometimes difficult builds) • Web site hosting • Publican is written in perl • Turn-off for new writers
- 13. Conversion From Publican to ReadTheDocs
- 15. 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
- 16. 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
- 17. 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
- 18. Gotchas • Table of Content headings • Table format • Code snippets • References
- 19. Build and Host
- 20. Build for RST projects Sphinx $sphinx-quickstart Drop in your .rst files and build $make html
- 21. Read The Docs
- 22. GitHub Integration From Publican to ReadTheDocs
- 24. Seamless integration of RTD with GitHub
- 27. i18n
- 28. README
- 29. Publican i18n Great support for localization Integrates with Transifex workflow
- 32. Early Results
- 33. Conclusions
- 34. • Easy to contribute to • Looking great • Localization support • Automated build • Remote hosting
- 35. Almost Done
- 36. Events CloudStack Collaboration Conference: Vegas, Santa-Clara, Amsterdam Denver April 9-11th Rumors of ApacheCon EU in BUDAPEST !!! Contributing to Apache CloudStack
- 37. 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.