cloudstack-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From sebgoa <>
Subject [UPDATE][DOCS][PROPOSAL] Move to .rst and new repos
Date Mon, 27 Jan 2014 16:25:48 GMT
Quick update on this thread.

I made some initial commits to the two new docs repo:;a=summary;a=summary

These were made by:
1- using publican to build a html-single output of the current documentation.
2- using pandoc to convert the single html page to .rst
3- build a sphinx project for each repo using sphinx-quickstart
4- moved the .rst file to the skeleton sphinx project
5- fixed Note and Warning tags 
6- fixed some issues with couple images not present or replication of reference

This leads to two successful build, even though there are still warning and lots of work to
do with the table of content.

To test the result I created two Read The Docs projects, the results is on-line:

This is clearly not finished and this will require more work to check the format, the conversion
with pandoc may have broken some things.

The end result so far is that I feel it is much easier to work with, just grab your favorite
editor and you can actually read the docs, and fix it.
I also right away deleted some chapters in the admin guide (concepts..) that were a copy of
the install guide.

I plan to do the same process for the release notes...


On Jan 22, 2014, at 6:27 PM, Alex Hitchins <> wrote:

> Personally, I think if possible;
> could go to a page with both sets available, linking
> My thinking is is easier to remember.
> I wonder if there is a SEO benefit to either option. Be good it the install and admin
guides we well crawled.
> Alex Hitchins
> +44 7788 423 969
> -----Original Message-----
> From: sebgoa []
> Sent: 22 January 2014 17:18
> To:
> Subject: [DOCS][PROPOSAL] Move to .rst and new repos
> Hi,
> Prior to the break we had a discussion to move to a new doc format RST.
> In investigating the process and the infra needed for this, David and I thought that
having a repo for each guide/book would be good.
> Otherwise the readthedocs build infra will create one massive pdf/epub, think ~400 pages.
> So David created couple repos:
> cloudstack-docs-admin.git
> cloudstack-docs-install.git
> Now we need to decide on CNAMEs for each guide, meaning that to get to the admin guide
(for instance) you will hit ...
> We propose to use:
> thoughts ? better ideas ?
> -Sebastien
> Need Enterprise Grade Support for Apache CloudStack?
> Our CloudStack Infrastructure Support<>
offers the best 24/7 SLA for CloudStack Environments.
> Apache CloudStack Bootcamp training courses
> **NEW!** CloudStack 4.2.1 training<>
> 18th-19th February 2014, Brazil. Classroom<>
> 17th-23rd March 2014, Region A. Instructor led, On-line<>
> 24th-28th March 2014, Region B. Instructor led, On-line<>
> 16th-20th June 2014, Region A. Instructor led, On-line<>
> 23rd-27th June 2014, Region B. Instructor led, On-line<>
> 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.

View raw message