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 02:37:04 GMT
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.  


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