[Owncloud] Documentation Repo Howto

[Arthur Schiwon]

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)