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

1,867
views

Published on

Published in: Technology, News & Politics

0 Comments
1 Like
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total Views
1,867
On Slideshare
0
From Embeds
0
Number of Embeds
3
Actions
Shares
0
Downloads
3
Comments
0
Likes
1
Embeds 0
No embeds

Report content
Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
No notes for slide

Transcript

  • 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: 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.