[IPython-dev] Quick launchpad guide for would-be contributors

[Brian Granger]

On Tue, Jun 3, 2008 at 1:21 PM, Fernando Perez <fperez.net at gmail.com> wrote:
> On Tue, Jun 3, 2008 at 11:45 AM, Brian Granger <ellisonbg.net at gmail.com> wrote:
>> Also, I have started a rst/Sphinx based developer's guidelines in
>> ipython1.  I based it on the wiki initially, but has more info on
>> certain fronts - especially on the stuff that is relevant to ipython1
>> merging with IPython.  When I do the merge of ipython1->IPython, I
>> will also merge the developer related things.
>>
>> This brings up a bigger issue.  I would like _all_ of our docs to be
>> Sphinx based.  And in my mind, the developer guidelines fall under
>> this.  I don't like having to maintain multiple documentation sets
>> (wiki + Sphinx) and I think the Sphinx docs are a better place for all
>> of these things, including the developer related things.  We should
>> save the wiki for things like the cookbook and the basic web presence
>> for IPython.  How does this sound?
>
> This has been very much in my mind, I just don't have the bandwidth to
> deal with all of it simultaneously.  But I'm growing increasingly
> annoyed at having docs in the wiki and in rst that are separate.  At
> the same time, the wiki has the advantage of lowering the barrier to
> external contributions in a way that rst docs don't quite achieve
> (they still require source editing and a patch).
>
> Ultimately the solution to this problem would be to have something
> like what is being now used for the numpy docstrings:
>
> http://sd-2116.dedibox.fr/pydocweb/wiki/Front Page/
>
> but applied to ALL documentation.  This is the ideal solution in the
> long run: everything in one place, casual users can contribute with a
> zero-overhead web interface, and the system automatically generates
> the changesets so that developers can apply them with minimal effort.

Except, I am not sure that having casual users contribute to the docs
without any review is a good idea.  In fact, with no review, there is
the possibility that wiki spam could make it into our docs in a major
release.  Also, even when you know rst+Sphinx it is easy to mess up
links, etc.  I would like to move gradually towards code review (but
not a formal process, I am thinking of people simply reviewing each
others branches before a merge) and a direct wiki->trunk connection is
a move in the opposite direction.  Here is what I have been thinking
of:

1) We (the ipython dev team) use the rst/Sphinx for any/all docs that
we are maintaining.

1) We encourage the usage of the wiki for unofficial, user contributed
docs, the cookbook, etc.

2) We encourage users to contribute official rst/Sphinx docs by
branching trunk, writing the docs and then requesting a review/merge.

> But integrating all that is more than we should tackle *right now*, I
> think.  So I'm all for the following as a compromise solution:
>
> 1. Put our dev guidelines in rst
> 2. I write a cron job to update nightly docs from the bzr mainline.
> 3. We make certain key wiki pages simply link to the relevant point in
> these auto-generated docs.

I think this sounds great.  I volunteer to get the docs
(IPython+ipython1) in shape if you can setup the cron job afterwards.

> I think it would make a neat topic for a sprint at scipy'08 to work on
> the full doc integration system...
>
> Cheers,
>
> f
>