Looks good to me. +1 The format is much more dev friendly so it might help with getting more people to write docs.
Cheers, Hugo On 9 dec. 2013, at 18:08, Sateesh Chodapuneedi <sateesh.chodapune...@citrix.com> wrote: > +1 for .rst. > Its more developer friendly! > > -Regards, > Sateesh > >> -----Original Message----- >> From: sebgoa [mailto:run...@gmail.com] >> Sent: 09 December 2013 17:24 >> To: dev@cloudstack.apache.org >> Cc: Radhika Puthiyetath; msweet....@gmail.com; Mike Tutkowski >> Subject: [DISCUSS][PROPOSAL] Move docs to .rst format and readthedocs >> >> Hi, >> >> There has been lots of discussion about docs over the last 3/4 months, in >> summary the issues are: >> >> -Difficult to maintain and keep website up to date (issues with lang and >> issues with pdf formatting lately) -Difficult to contribute to easily, >> docbook is fine but tedious to work on. >> -Errors in the docs don't get properly fixed -Mix of OS information -Lack of >> content for certain features -Docs release cycle. Docs have bugs >> that will never get fixed in that specific release (because we see it as >> code release) >> >> To remedy some of those issues and work on a new release process specific to >> docs we moved the docs to its own repo: >> >> https://git-wip-us.apache.org/repos/asf?p=cloudstack-docs.git >> >> *I propose that we move away from docbook and use a more readable format: >> restructuredtext* >> >> I have worked on a prototype that uses restructured text: >> http://docutils.sourceforge.net/rst.html >> >> This format makes it extremely easy to write docs. Existing docbook content >> could be converted to .rst using a tool like pandoc: >> http://johnmacfarlane.net/pandoc/ >> >> *In addition to changing the format I propose that we use readthedocs.org* >> >> This will help with the release and build of the docs. readthedocs grabs the >> docs from a git repo, builds html, pdf and epub. >> It can also maintain several releases. We can apply a specific -theme- to >> our docs. >> >> See a prototype here: >> >> http://cloudstack.readthedocs.org/en/latest/ >> >> *I propose that we move to this as early as 4.3 documentation* >> >> Assuming this proposal passes, we would need to: >> >> -re-architect the repo >> -create the proper cnames to be in accordance with trademark guidelines -we >> can decide what content to keep or not and convert what we >> keep. >> -decide how we organize the content >> -start accepting pull requests (noting that pages can be edited directly >> from github) -make a first release of this new doc site at the same >> time than 4.3 release. >> >> >> Thoughts, flames ? >> >> >> -Sebastien
