cloudstack-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From <nicolas.lamira...@orange.com>
Subject Re: [DISCUSS][PROPOSAL] Move docs to .rst format and readthedocs
Date Tue, 10 Dec 2013 14:13:38 GMT
+1 for .rst !

Le 09/12/2013 12:54, sebgoa a écrit :
> 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
> 


-- 
Nicolas Lamirault

_________________________________________________________________________________________________________________________

Ce message et ses pieces jointes peuvent contenir des informations confidentielles ou privilegiees
et ne doivent donc
pas etre diffuses, exploites ou copies sans autorisation. Si vous avez recu ce message par
erreur, veuillez le signaler
a l'expediteur et le detruire ainsi que les pieces jointes. Les messages electroniques etant
susceptibles d'alteration,
Orange decline toute responsabilite si ce message a ete altere, deforme ou falsifie. Merci.

This message and its attachments may contain confidential or privileged information that may
be protected by law;
they should not be distributed, used or copied without authorisation.
If you have received this email in error, please notify the sender and delete this message
and its attachments.
As emails may be altered, Orange is not liable for messages that have been modified, changed
or falsified.
Thank you.


Mime
View raw message