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

[Fernando Perez]

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.

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 it would make a neat topic for a sprint at scipy'08 to work on
the full doc integration system...

Cheers,

f