You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@cloudstack.apache.org by sebgoa <ru...@gmail.com> on 2013/12/09 12:54:12 UTC
[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
Re: [DISCUSS][PROPOSAL] Move docs to .rst format and readthedocs
Posted by David Nalley <da...@gnsa.us>.
>
> -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 ?
>
>
So I was the one that picked Publican for CloudStack in the pre-ACS
days. I like publican, it generally makes sense to me, seems to work
well, and despite the fact that it's DocBook XML with specialized
tools for generating finished documentation, it does the job very
well.
That said, I see a few problems with publican; namely:
* DocBook XML is something folks have to learn before being able to
contribute (e.g. the barrier to participate is higher)
* The build/publish process is difficult at best. Currently I think
that only Joe Brockmeier and I know how to do so. (we are SPOFs)
I actually looked (at Joe's suggestion) for something else many months
ago; and there didn't seem anything that was close to competent for
generation of PDFs and EPUBs. I reluctantly tried RTD when Sebastien
showed it to me - and was literally blown away - formatting/syntax is
simpler, publishing is dead easy; and not dependent on an individual.
I am +1 for this change; I think it makes life simpler for anyone who
wants to work on docs, and changes next to nothing for the folks who
only consume them.
--David
Re: [DISCUSS][PROPOSAL] Move docs to .rst format and readthedocs
Posted by ni...@orange.com.
+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.
Re: [DISCUSS][PROPOSAL] Move docs to .rst format and readthedocs
Posted by Chiradeep Vittal <Ch...@citrix.com>.
Nice.
According to http://en.wikipedia.org/wiki/Lightweight_markup_language and
see that it is quite similar to Markdown.
On 12/9/13 2:18 PM, "Hugo Trippaers" <hu...@trippaers.nl> wrote:
>Looks good to me. +1
>
>The format is much more dev friendly so it might help with getting more
>people to write docs.
>
>Cheers,
>
>Hugo
>
>
>On 9 dec. 2013, at 18:08, Sateesh Chodapuneedi
><sa...@citrix.com> wrote:
>
>> +1 for .rst.
>> Its more developer friendly!
>>
>> -Regards,
>> Sateesh
>>
>>> -----Original Message-----
>>> From: sebgoa [mailto:runseb@gmail.com]
>>> Sent: 09 December 2013 17:24
>>> 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
>
RE: [DISCUSS][PROPOSAL] Move docs to .rst format and readthedocs
Posted by Frank Zhang <Fr...@citrix.com>.
+1.
And suggest using Sphinx with the plugin http://bronto.github.io/javasphinx/
> -----Original Message-----
> From: Trippie [mailto:trippie@gmail.com] On Behalf Of Hugo Trippaers
> Sent: Monday, December 09, 2013 2:19 PM
> To: dev@cloudstack.apache.org
> Cc: Radhika Puthiyetath; msweet.dev@gmail.com; Mike Tutkowski
> Subject: Re: [DISCUSS][PROPOSAL] Move docs to .rst format and readthedocs
>
> Looks good to me. +1
>
> The format is much more dev friendly so it might help with getting more
> people to write docs.
>
> Cheers,
>
> Hugo
>
>
> On 9 dec. 2013, at 18:08, Sateesh Chodapuneedi
> <sa...@citrix.com> wrote:
>
> > +1 for .rst.
> > Its more developer friendly!
> >
> > -Regards,
> > Sateesh
> >
> >> -----Original Message-----
> >> From: sebgoa [mailto:runseb@gmail.com]
> >> Sent: 09 December 2013 17:24
> >> 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
Re: [DISCUSS][PROPOSAL] Move docs to .rst format and readthedocs
Posted by Hugo Trippaers <hu...@trippaers.nl>.
Looks good to me. +1
The format is much more dev friendly so it might help with getting more people to write docs.
Cheers,
Hugo
On 9 dec. 2013, at 18:08, Sateesh Chodapuneedi <sa...@citrix.com> wrote:
> +1 for .rst.
> Its more developer friendly!
>
> -Regards,
> Sateesh
>
>> -----Original Message-----
>> From: sebgoa [mailto:runseb@gmail.com]
>> Sent: 09 December 2013 17:24
>> 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
RE: [DISCUSS][PROPOSAL] Move docs to .rst format and readthedocs
Posted by Sateesh Chodapuneedi <sa...@citrix.com>.
+1 for .rst.
Its more developer friendly!
-Regards,
Sateesh
> -----Original Message-----
> From: sebgoa [mailto:runseb@gmail.com]
> Sent: 09 December 2013 17:24
> 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
RE: [DISCUSS][PROPOSAL] Move docs to .rst format and readthedocs
Posted by Radhika Puthiyetath <ra...@citrix.com>.
Hi,
+ 0 because I have not yet got time to understand the tool.
I also have to understand what it takes to pick up the tool. I am not a developer to sightlessly say Yes. If developers are ready to contribute the doc for their features, I am perfectly fine!
If you are planning it for 4.3 docs, I might not be able to help. I can develop content only in DocBook due to time constraints. If you are keen on rolling it out for 4.3, I would request the doc contributors to convert them to RST format, or let developers contribute their feature docs in RST format.
Jessica T has moved out from CloudStack, and I am kind of a single-person army from Citrix side. Therefore, my contribution might be limited to ASFCS.
-Radhika
-----Original Message-----
From: Sebastien Goasguen [mailto:runseb@gmail.com]
Sent: Tuesday, December 10, 2013 1:01 PM
To: dev@cloudstack.apache.org
Cc: Radhika Puthiyetath; msweet.dev@gmail.com; Mike Tutkowski
Subject: Re: [DISCUSS][PROPOSAL] Move docs to .rst format and readthedocs
On Dec 9, 2013, at 9:37 PM, Animesh Chaturvedi <an...@citrix.com> wrote:
> 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.
>
docs are not in the 4.3 code branch. it's different releases...
>
> 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
Re: [SUMMARY][DISCUSS][PROPOSAL] Move docs to .rst format and readthedocs
Posted by David Nalley <da...@gnsa.us>.
In IRC Sebastien was noting that the content was already becoming
quite large for a single 'site'/pdf/epub, and it soon gets
bewildering.
I am going to open up a few additional git repos and see if that
alleviates the issue.
--David
On Sat, Dec 21, 2013 at 12:37 PM, Sebastien Goasguen <ru...@gmail.com> wrote:
> Looks like we have a consensus,
>
> I will take this on and make sure it gets implemented as fast as possible.
>
> If any one wants to start to contribute docs over christmas, please send pr to:
> https://github.com/runseb/acsdocs
>
> Thanks to Shankar for already sending a trouble shooting guide.
>
> You can also send a rst or markdown file to review board, I will pull, convert and merge everything.
> Once the move is made I will document the entire process.
>
> Merry Christmas everyone,
>
> -Sebastien
>
>
> On Dec 19, 2013, at 4:47 PM, Animesh Chaturvedi <an...@citrix.com> wrote:
>
>>
>>
>> -----Original Message-----
>> From: Animesh Chaturvedi [mailto:animesh.chaturvedi@citrix.com]
>> Sent: Tuesday, December 10, 2013 9:24 AM
>> To: dev@cloudstack.apache.org
>> Cc: Radhika Puthiyetath; msweet.dev@gmail.com; Mike Tutkowski
>> Subject: RE: [DISCUSS][PROPOSAL] Move docs to .rst format and readthedocs
>>
>>
>>
>> -----Original Message-----
>> From: Sebastien Goasguen [mailto:runseb@gmail.com]
>> Sent: Monday, December 09, 2013 11:31 PM
>> To: dev@cloudstack.apache.org
>> Cc: Radhika Puthiyetath; msweet.dev@gmail.com; Mike Tutkowski
>> Subject: Re: [DISCUSS][PROPOSAL] Move docs to .rst format and readthedocs
>>
>>
>> On Dec 9, 2013, at 9:37 PM, Animesh Chaturvedi <an...@citrix.com> wrote:
>>
>>> 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.
>>>
>>
>> docs are not in the 4.3 code branch. it's different releases...
>>
>> Animesh> But they will be released together.
>> [Animesh] Sebastien what is the planned ETA for the conversion to RST. ACS 4.3 planned RC date is 1/10 and I would like to have the documentation ready by 1/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
>>
>
[SUMMARY][DISCUSS][PROPOSAL] Move docs to .rst format and readthedocs
Posted by Sebastien Goasguen <ru...@gmail.com>.
Looks like we have a consensus,
I will take this on and make sure it gets implemented as fast as possible.
If any one wants to start to contribute docs over christmas, please send pr to:
https://github.com/runseb/acsdocs
Thanks to Shankar for already sending a trouble shooting guide.
You can also send a rst or markdown file to review board, I will pull, convert and merge everything.
Once the move is made I will document the entire process.
Merry Christmas everyone,
-Sebastien
On Dec 19, 2013, at 4:47 PM, Animesh Chaturvedi <an...@citrix.com> wrote:
>
>
> -----Original Message-----
> From: Animesh Chaturvedi [mailto:animesh.chaturvedi@citrix.com]
> Sent: Tuesday, December 10, 2013 9:24 AM
> To: dev@cloudstack.apache.org
> Cc: Radhika Puthiyetath; msweet.dev@gmail.com; Mike Tutkowski
> Subject: RE: [DISCUSS][PROPOSAL] Move docs to .rst format and readthedocs
>
>
>
> -----Original Message-----
> From: Sebastien Goasguen [mailto:runseb@gmail.com]
> Sent: Monday, December 09, 2013 11:31 PM
> To: dev@cloudstack.apache.org
> Cc: Radhika Puthiyetath; msweet.dev@gmail.com; Mike Tutkowski
> Subject: Re: [DISCUSS][PROPOSAL] Move docs to .rst format and readthedocs
>
>
> On Dec 9, 2013, at 9:37 PM, Animesh Chaturvedi <an...@citrix.com> wrote:
>
>> 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.
>>
>
> docs are not in the 4.3 code branch. it's different releases...
>
> Animesh> But they will be released together.
> [Animesh] Sebastien what is the planned ETA for the conversion to RST. ACS 4.3 planned RC date is 1/10 and I would like to have the documentation ready by 1/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
>
RE: [DISCUSS][PROPOSAL] Move docs to .rst format and readthedocs
Posted by Animesh Chaturvedi <an...@citrix.com>.
-----Original Message-----
From: Animesh Chaturvedi [mailto:animesh.chaturvedi@citrix.com]
Sent: Tuesday, December 10, 2013 9:24 AM
To: dev@cloudstack.apache.org
Cc: Radhika Puthiyetath; msweet.dev@gmail.com; Mike Tutkowski
Subject: RE: [DISCUSS][PROPOSAL] Move docs to .rst format and readthedocs
-----Original Message-----
From: Sebastien Goasguen [mailto:runseb@gmail.com]
Sent: Monday, December 09, 2013 11:31 PM
To: dev@cloudstack.apache.org
Cc: Radhika Puthiyetath; msweet.dev@gmail.com; Mike Tutkowski
Subject: Re: [DISCUSS][PROPOSAL] Move docs to .rst format and readthedocs
On Dec 9, 2013, at 9:37 PM, Animesh Chaturvedi <an...@citrix.com> wrote:
> 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.
>
docs are not in the 4.3 code branch. it's different releases...
Animesh> But they will be released together.
[Animesh] Sebastien what is the planned ETA for the conversion to RST. ACS 4.3 planned RC date is 1/10 and I would like to have the documentation ready by 1/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
Re: [DISCUSS][PROPOSAL] Move docs to .rst format and readthedocs
Posted by Marty Sweet <ms...@gmail.com>.
+1, also a clearer Wiki to show how to contribute towards docs would be
good, including what repo to fetch - I assume this would be made easier
using Github Pull requests?
On the Wiki:
GIT Usage - with Examples
Conventional Markup (Linking to documentation can be daunting to some
users, causing them not to contribute - as with the case with Publican)
Marty
On Tue, Dec 10, 2013 at 5:36 PM, Francois Gaudreault <
fgaudreault@cloudops.com> wrote:
> +1. Anything to move away from "manual" docbook is good!!! Now we won't
> have any reasons not to update the documentation if we find bugs in it :S
>
> asciidoc would have been another possibility tho... but reST is fine :)
>
> Francois
>
>
> On Tue, Dec 10, 2013 at 12:23 PM, Animesh Chaturvedi <
> animesh.chaturvedi@citrix.com> wrote:
>
> >
> >
> > -----Original Message-----
> > From: Sebastien Goasguen [mailto:runseb@gmail.com]
> > Sent: Monday, December 09, 2013 11:31 PM
> > To: dev@cloudstack.apache.org
> > Cc: Radhika Puthiyetath; msweet.dev@gmail.com; Mike Tutkowski
> > Subject: Re: [DISCUSS][PROPOSAL] Move docs to .rst format and readthedocs
> >
> >
> > On Dec 9, 2013, at 9:37 PM, Animesh Chaturvedi <
> > animesh.chaturvedi@citrix.com> wrote:
> >
> > > 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.
> > >
> >
> > docs are not in the 4.3 code branch. it's different releases...
> >
> > Animesh> But they will be released together.
> >
> > >
> > > 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
> >
> >
>
Re: [DISCUSS][PROPOSAL] Move docs to .rst format and readthedocs
Posted by Francois Gaudreault <fg...@cloudops.com>.
+1. Anything to move away from "manual" docbook is good!!! Now we won't
have any reasons not to update the documentation if we find bugs in it :S
asciidoc would have been another possibility tho... but reST is fine :)
Francois
On Tue, Dec 10, 2013 at 12:23 PM, Animesh Chaturvedi <
animesh.chaturvedi@citrix.com> wrote:
>
>
> -----Original Message-----
> From: Sebastien Goasguen [mailto:runseb@gmail.com]
> Sent: Monday, December 09, 2013 11:31 PM
> To: dev@cloudstack.apache.org
> Cc: Radhika Puthiyetath; msweet.dev@gmail.com; Mike Tutkowski
> Subject: Re: [DISCUSS][PROPOSAL] Move docs to .rst format and readthedocs
>
>
> On Dec 9, 2013, at 9:37 PM, Animesh Chaturvedi <
> animesh.chaturvedi@citrix.com> wrote:
>
> > 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.
> >
>
> docs are not in the 4.3 code branch. it's different releases...
>
> Animesh> But they will be released together.
>
> >
> > 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
>
>
RE: [DISCUSS][PROPOSAL] Move docs to .rst format and readthedocs
Posted by Animesh Chaturvedi <an...@citrix.com>.
-----Original Message-----
From: Sebastien Goasguen [mailto:runseb@gmail.com]
Sent: Monday, December 09, 2013 11:31 PM
To: dev@cloudstack.apache.org
Cc: Radhika Puthiyetath; msweet.dev@gmail.com; Mike Tutkowski
Subject: Re: [DISCUSS][PROPOSAL] Move docs to .rst format and readthedocs
On Dec 9, 2013, at 9:37 PM, Animesh Chaturvedi <an...@citrix.com> wrote:
> 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.
>
docs are not in the 4.3 code branch. it's different releases...
Animesh> But they will be released together.
>
> 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
Re: [DISCUSS][PROPOSAL] Move docs to .rst format and readthedocs
Posted by Sebastien Goasguen <ru...@gmail.com>.
On Dec 9, 2013, at 9:37 PM, Animesh Chaturvedi <an...@citrix.com> wrote:
> 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.
>
docs are not in the 4.3 code branch. it's different releases...
>
> 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
RE: [DISCUSS][PROPOSAL] Move docs to .rst format and readthedocs
Posted by Animesh Chaturvedi <an...@citrix.com>.
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
RE: [DISCUSS][PROPOSAL] Move docs to .rst format and readthedocs
Posted by Geoff Higginbottom <ge...@shapeblue.com>.
+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.higginbottom@shapeblue.com
-----Original Message-----
From: sebgoa [mailto:runseb@gmail.com]
Sent: 09 December 2013 11:54
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
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.