Going from Publican to Read the Docs
summary
Apache CloudStack moves documentation from DocBook/Publican to reStructuredText, Sphinx and Read the Docs to get real contributions. Migration uses a single huge HTML export and Pandoc conversion hack to turn ~540 DocBook files and ~43,000 lines of XML into rst, then hosts on Read the Docs with Read the Docs + GitHub edit button and automated builds on each commit. Localization keeps work in Transifex with 83 translators and a first Japanese build already serving.
AI-written summary · about
chapters (29)
- 0:00Introduction
- 0:40Eucalyptus
- 2:10Publican
- 2:38fedora
- 2:57challenges
- 3:12OReilly
- 4:13Publican Overview
- 4:59XML Files
- 6:14Nested Loop
- 6:51Documentation
- 7:45Other Issues
- 8:48What to Convert
- 10:27Restructured Text
- 11:01Panda
- 11:52Dogcook
- 12:22Restructure Text
- 13:02Build
- 13:52HTML Organization
- 14:23Read the Docs
- 14:52Social Coding
- 15:03Japanese
- 15:19Service Books
- 16:29End Result
- 18:14Transifex
- 19:36Crucifix
- 19:56New site
- 20:49Why we changed format
- 21:22Next week
- 21:48Contact
related talks
35mSwitching from Sphinx to Markdown
32mSwitching from Sphinx to Markdown
33mWrite the Docs!
45mOne AWS team’s move to docs as code
45mIntroduction to Sphinx & Read the Docs
23mTreating Documentation like Code: a Practical Account
40mFrom resistance to adoption: navigating the challenges of docs-like-code
44mPushing documentation (so it doesn't hurt anymore)