[SciPy-dev] Docstrings patches

[Bill Baxter]

Automating all that seems pretty tricky, though valuable if someone
can find the time to do it.

But one similar idea that might be easier to get going would be to set
up said wiki with a fixed base url, and then write some utility
functions for scipy that let you do something like:

scipy.webdoc(scipy.hamming)

to launch the user's browser and take it to that wiki page.  These
pages can have more detail, examples, and cross-referencing than is
possible with the regular built-in docs, and being wiki, could also
have discussions attached.

The main issue I see with straight wiki, is that it would be nice to
impose some structure on the docs, such as One Line Description |
Brief Description | SeeAlso | Examples | Discussion, but with wiki all
you get is one big blob of text.

--bb

On 10/22/06, Mark Koudritsky <kamrik at gmail.com> wrote:
> Was the possibility of editing the docstrings in a wiki style ever discussed?
>
> I think it can be done with a special wiki which has a page for every
> docstring in the sources (not every comment, but every docstring
> intended for the user). Some script can be run once in a while that
> will take the docstrings from the wiki and insert them into the
> sources. Such a system would very significantly lower the barrier for
> contributing to documentation.
>
> Of course, the system is not trivial, it should check the docstrings
> from the wiki to avoid "injection attacks" etc. etc. But it's not too
> complicated either.
>
> Does anybody know if a similar system already exists somewhere?
>
> Anyway, I call for discussion of this possibility.
>
> Regards
>
>    - Mark
> _______________________________________________
> Scipy-dev mailing list
> Scipy-dev at scipy.org
> http://projects.scipy.org/mailman/listinfo/scipy-dev
>