[Owncloud] Documentation Repo Howto

[Arthur Schiwon]

On Saturday, December 08, 2012 05:31:29 AM Bernhard Posselt wrote:
> The php extension is python 2 only ;)

Confirmed, throws an error with Python 3.


> 
> On 12/08/2012 01:53 AM, Arthur Schiwon wrote:
> > Thanks, Danimo, thats overwhelming!
> > 
> >> Python 2.6 or newer
> >> Sphinx for Python 2.x (usually part of any Linux distribution or in Mac-
> > 
> > Ports)
> > 
> > Python 3 resp. Sphinx for Python 3 is very very bad, eats little children,
> > kittens and all those things?
> > 
> > Cheers
> > Arthur
> > 
> > On Wednesday, November 28, 2012 08:29:41 PM Daniel Molkentin wrote:
> >> Hi,
> >> 
> >> I realized I never really introduced our documentation repository, sorry
> >> for that. This mail tries to fix this as I see a lot of movement again
> >> in the documentation repo. It is changing almost every hour now, which
> >> is really awesome. I want to take the opportunity to , we have two
> >> branches to work on on the server, master and stable45. The naming
> >> conventions follow the ones in core and apps.
> >> 
> >> All documentation that concerns both 4.5 and master should go into
> >> stable45
> >> and will be merged into master regulary. Everything that only concerns
> >> master should only be documented in master for 5.0. However, this does
> >> not
> >> mean a free ticket to abandon stable45.
> >> 
> >> I know that for most of us the only thing less rewarding than
> >> documentation
> >> is documenting what many of you see as 'yesterdays software', but this is
> >> what people use, and should be using. So please help them.
> >> 
> >> To help matters, I propose the following commit policy for the
> >> documentation repository:
> >> 
> >> - Please push only after running at least "make html", indeally also
> >> "make
> >> latexpdf" ran locally without problems. - If you broke it, you will
> >> receive
> >> mail from Mr. Jenkins. If you are unsure how to fix it, get in touch with
> >> me - Only commit to master if you have documented the same in stable45 or
> >> the feature didn't exist in 4.5, do so by merging (stable-first approach)
> >> -
> >> Exceptions are in place for GCI. Please get in touch with me. I will do
> >> the
> >> painful merging - If you document something in stable45, you are
> >> responsible for landing it in master through merging. If you are unsure
> >> how
> >> to do that, please get in touch with me. - I will also take care of
> >> documentation created through PRs.
> >> 
> >> FAQ:
> >> 
> >> Q: What should I look at as a reference for good documentation style?
> >> A: The Sphinx documentation (http://sphinx-doc.org/contents.html) itself
> >> is
> >> very good. Every page has a "Show source" section that shows how it was
> >> made.
> >> 
> >> Q: For my topic, should I create topic.rst or topic/index.rst?
> >> 
> >> A: Do not create a directory. We can still refactor into a directory
> >> later
> >> on. If you sit on top of a huge pile of documentation on a single topic,
> >> I
> >> am glad to assist you with your luxury problem :-)
> >> 
> >> Q: Why not use cherry-picking from master to stable45?
> >> 
> >> A:  Cherry-picking only works if we have someone who makes sure the
> >> cherrys
> >> actually get picked. This also involves adjusting the documentation to
> >> stable45, which requires domain specific knowledge of both versions. If
> >> you
> >> still would like to volunteer, speak up.
> >> 
> >> Q: This doesn't look like a documentation at all, it doesn't even have an
> >> introduction and a proper structure!
> >> 
> >> A: Yes, I know. Working on that. Volunteers welcome.
> >> 
> >> Q: LaTeX barfs on my fancy table. What can I do to fix this?
> >> 
> >> A: Avoid overly complex tables. Complex tables should usually broken down
> >> into simple tables + text anyway. Remember, people might read this on
> >> their
> >> eBook reader! Everything with multiline columns is something that the
> >> latex
> >> generator frowns upon. In general though, the latex generator is just a
> >> lot
> >> more picky over a broken ascii table art misplacement than the HTML
> >> equivalent is. Double-check your markup.
> >> 
> >> Cheers,
> >> 
> >>   Daniel
> >> 
> >> --
> >> www.owncloud.com - Your Data, Your Cloud, Your Way!
> >> 
> >> ownCloud GmbH, GF: Markus Rex, Holger Dyroff
> >> Schloßäckerstrasse 26a, 90443 Nürnberg, HRB 28050 (AG Nürnberg)
> > 
> > _______________________________________________
> > Owncloud mailing list
> > Owncloud at kde.org
> > https://mail.kde.org/mailman/listinfo/owncloud
> 
> _______________________________________________
> Owncloud mailing list
> Owncloud at kde.org
> https://mail.kde.org/mailman/listinfo/owncloud