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 <run...@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.chaturv...@citrix.com> wrote: > >> >> >> -----Original Message----- >> From: Animesh Chaturvedi [mailto:animesh.chaturv...@citrix.com] >> Sent: Tuesday, December 10, 2013 9:24 AM >> To: dev@cloudstack.apache.org >> Cc: Radhika Puthiyetath; msweet....@gmail.com; Mike Tutkowski >> Subject: RE: [DISCUSS][PROPOSAL] Move docs to .rst format and readthedocs >> >> >> >> -----Original Message----- >> From: Sebastien Goasguen [mailto:run...@gmail.com] >> Sent: Monday, December 09, 2013 11:31 PM >> To: dev@cloudstack.apache.org >> Cc: Radhika Puthiyetath; msweet....@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.chaturv...@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:run...@gmail.com] >>> Sent: Monday, December 09, 2013 3:54 AM >>> 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 >> >
