+1 from me, anything to make updating Docs easier has to be a positive Regards
Geoff Higginbottom D: +44 20 3603 0542 | S: +44 20 3603 0540 | M: +447968161581 geoff.higginbot...@shapeblue.com -----Original Message----- From: sebgoa [mailto:run...@gmail.com] Sent: 09 December 2013 11:54 To: dev@cloudstack.apache.org Cc: Radhika Puthiyetath; msweet....@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 This email and any attachments to it may be confidential and are intended solely for the use of the individual to whom it is addressed. Any views or opinions expressed are solely those of the author and do not necessarily represent those of Shape Blue Ltd or related companies. If you are not the intended recipient of this email, you must neither take any action based upon its contents, nor copy or show it to anyone. Please contact the sender if you believe you have received this email in error. Shape Blue Ltd is a company incorporated in England & Wales. ShapeBlue Services India LLP is a company incorporated in India and is operated under license from Shape Blue Ltd. Shape Blue Brasil Consultoria Ltda is a company incorporated in Brasil and is operated under license from Shape Blue Ltd. ShapeBlue is a registered trademark.
