Nice. According to http://en.wikipedia.org/wiki/Lightweight_markup_language and see that it is quite similar to Markdown.
On 12/9/13 2:18 PM, "Hugo Trippaers" <h...@trippaers.nl> wrote: >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 >
