cloudstack-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From sebgoa <>
Subject [DISCUSS][PROPOSAL] Move docs to .rst format and readthedocs
Date Mon, 09 Dec 2013 11:54:12 GMT

There has been lots of discussion about docs over the last 3/4 months, in summary the issues

-Difficult to maintain and keep website up to date (issues with lang and issues with pdf formatting
-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:

*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:

This format makes it extremely easy to write docs. Existing docbook content could be converted
to .rst using a tool like pandoc:

*In addition to changing the format I propose that we use*

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:

*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 ?

View raw message