[IPython-dev] Fwd: IPython documentation

[Pauli Virtanen]

On 2008/6/12 Fernando Perez wrote:
[clip]
> One thing that I've been mulling is using the new scipy doc system
> 
> http://sd-2116.dedibox.fr/pydocweb/wiki/Front%20Page/
> 
> for the manuals as well.  I know it's doable, I just don't know right
> now how closely tied to docstring editing (the original purpose) it
> is.  Stefan can tell us...

Actually using it also for manuals could be in the interest of the Scipy
documentation project too.

The system itself is not really tied to docstring editing: what needs to
be done depends on whether you need 3-way merging with SVN (or bzr or
whatever) or not.

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.

	Pauli