Hi, + 0 because I have not yet got time to understand the tool.
I also have to understand what it takes to pick up the tool. I am not a developer to sightlessly say Yes. If developers are ready to contribute the doc for their features, I am perfectly fine! If you are planning it for 4.3 docs, I might not be able to help. I can develop content only in DocBook due to time constraints. If you are keen on rolling it out for 4.3, I would request the doc contributors to convert them to RST format, or let developers contribute their feature docs in RST format. Jessica T has moved out from CloudStack, and I am kind of a single-person army from Citrix side. Therefore, my contribution might be limited to ASFCS. -Radhika -----Original Message----- From: Sebastien Goasguen [mailto:run...@gmail.com] Sent: Tuesday, December 10, 2013 1:01 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 On Dec 9, 2013, at 9:37 PM, Animesh Chaturvedi <animesh.chaturv...@citrix.com> wrote: > I am +1 to make documentation easier but we just passed code freeze for 4.3 > and I feel we need to do it after 4.3. > docs are not in the 4.3 code branch. it's different releases... > > Animesh > > -----Original Message----- > From: sebgoa [mailto:run...@gmail.com] > Sent: Monday, December 09, 2013 3:54 AM > 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
