cloudstack-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Animesh Chaturvedi <animesh.chaturv...@citrix.com>
Subject RE: [DISCUSS][PROPOSAL] Move docs to .rst format and readthedocs
Date Tue, 10 Dec 2013 17:23:34 GMT


-----Original Message-----
From: Sebastien Goasguen [mailto:runseb@gmail.com] 
Sent: Monday, December 09, 2013 11:31 PM
To: dev@cloudstack.apache.org
Cc: Radhika Puthiyetath; msweet.dev@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.chaturvedi@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> But they will be released together. 

> 
> Animesh
> 
> -----Original Message-----
> From: sebgoa [mailto:runseb@gmail.com] 
> Sent: Monday, December 09, 2013 3:54 AM
> 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