[Owncloud] Documentation Repo Howto

[Bernhard Posselt]

The php extension is python 2 only ;)

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