cloudstack-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Chiradeep Vittal <Chiradeep.Vit...@citrix.com>
Subject Re: [DISCUSS][PROPOSAL] Move docs to .rst format and readthedocs
Date Mon, 09 Dec 2013 23:47:19 GMT
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" <hugo@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.chodapuneedi@citrix.com> wrote:
>
>> +1 for .rst.
>> Its more developer friendly!
>> 
>> -Regards,
>> Sateesh
>> 
>>> -----Original Message-----
>>> From: sebgoa [mailto:runseb@gmail.com]
>>> Sent: 09 December 2013 17:24
>>> To: dev@cloudstack.apache.org
>>> Cc: Radhika Puthiyetath; msweet.dev@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
>


Mime
View raw message