[wdmmg-dev] commit messages and other conventions

Mon Mar 21 17:46:30 UTC 2011

--On Sonntag, März 20, 2011 13:42:38 +0100 Friedrich Lindenberg 
<friedrich.lindenberg at okfn.org> wrote:

> Hi,
>
> On Thu, Mar 17, 2011 at 12:51 PM, Carsten Senger <senger at rehfisch.de>
> wrote:
>> While at it could somebody review the current state of the documentation?
>> It's sphinx based. If you have sphinx installed in your virtualenv it
>> will also build the small pieces of api documentation too.
>> I've restructured INSTALL and README, updated it and put it into /doc
>> without a deep knowledge about open spending, so there are maybe some
>> errors and missing information.
>
> This is beautiful even now, although we should really find some rules
> on what goes into the wiki and what we should put into sphinx: I would
> propose leaving the domain model documentation in the wiki as it might
> be useful to link it to and from other wiki pages seamlessly, while
> "How to write a loader" could go into sphinx?

I'd prefere to move all detailed technical docs into sphinx. We should
publish the generated sphinx docs and find a way to link to them from the
wiki. I don't know possible solutions in media wiki. Simple stub pages
should do.

There are some advantages to do it in the repository:
* They are versioned along with the code.
* it's mandatory to update them along with code changes (or at least
  more obvious)
* I can use an editor with rest support ;)

[...]

..Carsten