[IPython-dev] Fwd: IPython documentation

[Fernando Perez]

On Thu, Jun 12, 2008 at 11:32 AM, Pauli Virtanen <pav at iki.fi> wrote:

> If yes, it's probably easiest to modify the docstring collector script
> to also collect text from given .rst files, implement support for text
> files in the patch generation, and adjust the logic in the web interface
> slightly so that it knows that the docstring standard shouldn't be
> enforced for some entries. All of this is not a lot of extra work.
>
> If 3-way merges are not needed, one could simply use the wiki
> functionality in the program as an RST editor, and possibly write some
> code to easily export multiple wiki pages at once.
>
> For writing Sphinx documents, some amount of work would probably be
> needed in adding support for the Sphinx special directives. Writing this
> code is probably the hardest part as it requires some familiarity with
> the internals of the docutils package.

I'm focusing right now on all the testing machinery (not completely
trivial, given that 'ipython is not python'), so I won't touch any of
this yet.  And I agree with Brian that at least our current system is
eminently functional, and we can write nice docs with little overhead
beyond the writing itself.

But if you do want to contribute on any of this (which sooner or later
ipython, numpy, scipy, matplotlib, proably sympy, etc will want), I
think that a solution that integrates with the version control backend
naturally would be the easiest.  I don't know how you guys implemented
it, but I'd think that simply:

- producing one wiki page per .rst/.txt in a given directory
- generating one local commit into a special branch per user-visible change

should be enough, no?  Then, the editors can merge/reject those
individual commits into the trunk.

But if this is too much work, the simple 'wiki as rst editor' approach
would suffice initially, as long as the user changes can be applied
into the tree with some near-zero-overhead process (beyond reading the
actual patch).

Still, I wouldn't worry too much about this for now. You guys are
using this heavily for numpy/scipy and that's the current focus.
Experience gained there will be reused by the other projects later.  A
good target would be to work on this at the Scipy'08 sprint; will you
be there?

Cheers,

f