Moving from Publican to Read The Docs

2,767 views

Published on

Published in: Technology, News & Politics
0 Comments
1 Like
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total views
2,767
On SlideShare
0
From Embeds
0
Number of Embeds
27
Actions
Shares
0
Downloads
14
Comments
0
Likes
1
Embeds 0
No embeds

No notes for slide

Moving from Publican to Read The Docs

  1. 1. Sebastien Goasguen, @sebgoa Going from Publican to Sphinx and RTD
  2. 2. IaaS Landscape
  3. 3. Going From Publican to ReadTheDocs
  4. 4. Insert Presentation Title Here
  5. 5. DocBook is great !
  6. 6. Publican is a build tool for documentation written in DocBook format “DocBook is a XML schema suited for Books and papers”
  7. 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. 8. Other issues • Localization / Internationalization / i18n support ( sometimes difficult builds) • Web site hosting • Publican is written in perl • Turn-off for new writers
  9. 9. Conversion From Publican to ReadTheDocs
  10. 10. Devs love Git/Github
  11. 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. 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. 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. 14. Gotchas • Table of Content headings • Table format • Code snippets • References
  15. 15. Build and Host
  16. 16. Build for RST projects Sphinx $sphinx-quickstart Drop in your .rst files and build $make html
  17. 17. Read The Docs
  18. 18. GitHub Integration From Publican to ReadTheDocs
  19. 19. Increasing Contributions
  20. 20. Seamless integration of RTD with GitHub
  21. 21. Activate Service Hooks
  22. 22. Drive-By Contributions…
  23. 23. i18n
  24. 24. README
  25. 25. Publican i18n Great support for localization Integrates with Transifex workflow
  26. 26. See Marcus’s talk
  27. 27. Early Results
  28. 28. Conclusions
  29. 29. • Easy to contribute to • Looking great • Localization support • Automated build • Remote hosting
  30. 30. Almost Done
  31. 31. Events CloudStack Collaboration Conference: Vegas, Santa-Clara, Amsterdam Denver April 9-11th Rumors of ApacheCon EU in BUDAPEST !!! Contributing to Apache CloudStack
  32. 32. 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.

×