+1. And suggest using Sphinx with the plugin http://bronto.github.io/javasphinx/
> -----Original Message----- > From: Trippie [mailto:trip...@gmail.com] On Behalf Of Hugo Trippaers > Sent: Monday, December 09, 2013 2:19 PM > To: dev@cloudstack.apache.org > Cc: Radhika Puthiyetath; msweet....@gmail.com; Mike Tutkowski > Subject: Re: [DISCUSS][PROPOSAL] Move docs to .rst format and readthedocs > > 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
