[SciPy-dev] Fwd: [sage-devel] numpy in SAGE, etc.
kamrik at gmail.com
Thu Dec 7 10:40:58 CST 2006
Even though I've recently suggested the following idea on this mailing
list and got rather pessimistic response, I'll try it once again.
I believe it's relatively easy to create a web site with one page per
docstringable entity in the sources (function, class, module …). This
page can be either freely editable by the readers in a wiki style or
can have the option to add comments at the bottom (which will be once
in a while integrated into the main text by an editor, MySQL online
docs work this way). The content of this page will be injected
(preferably by an automatic script) as the doctring into the
appropriate function before releasing a new build of the package (this
last stage is the only non trivial one).
One argument against wiki style documentation was that it tends to get
messy. I believe that if the system suggests (rather than imposes)
some structure, the mess could be avoided. For example the basic
structure of page per entity + some standard template for the page
(like the one suggested by William) would be sufficient to maintain a
reasonable degree of order.
More information about the Scipy-dev