cloudstack-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From David Nalley <da...@gnsa.us>
Subject Re: [SUMMARY][DISCUSS][PROPOSAL] Move docs to .rst format and readthedocs
Date Wed, 22 Jan 2014 02:25:37 GMT
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 <runseb@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 <animesh.chaturvedi@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 <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] 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
>>
>

Mime
View raw message