[Numpy-discussion] MoinMoin <-> docstrings gateway

[dieter h]

On Mon, May 5, 2008 at 1:48 AM, Gael Varoquaux
<gael.varoquaux at normalesup.org> wrote:
> On Mon, May 05, 2008 at 03:17:20AM +0300, Pauli Virtanen wrote:
>  > Some time ago there was discussion about MoinMoin <-> docstrings
>  > gateway. Did it produce some results?
>
>  My girlfriend, Emmanuelle, (Cced, I am not sure she follows this mailing
>  list) has been working on this, with some progress.
>
>
>  > Anyway, I threw a bit of code together. There's something between a
>  > proof-of-concept and final product running now on my desktop machine.
>  > You can play with it here:
>
>  >       http://pvx.homeip.net/pTSc0V/TestWiki
>
>  Sweet. Some comments:
>
>  * A lot of the docstrings are not valid rst. This is not your fault, but
>   we will had to fix this in the long run.


I humbly suggest Sphinx[1] as the generating tool and markup rather
than just regular ReST. I'm in the process of converting all of my
local documentation to this engine's format.

As it's maturing, I find Sphinx to be on a path of being an ideal
referencing tool (considering my desire for dialog and effort, towards
standardizing documentation in the floss community. Improving pinpoint
referencing is one of future focus for me).

For example, NumpyBook is much more accessible to me now than it was
in .pdf. I'll be sending Travis a copy when I'm finished finalizing
the formating, after the just now automated translation. When he's
ready to release numpybook to the public domain, he may consider it
useful.

Btw, I think an excellent model of documentation topology/formatting
is that for the Qt toolkit (online). Take a look if your not familiar
with it. I might add their docs, options of cross-referenced api code
as well as internals for code junkies.

Are there others out there as focussed as I am on the 'science' of
useful documentation.

[1] http://sphinx.pocoo.org/index.html


>
>  * I would prefer if the main page was broken up into one per function. I
>   know this is the way it is in the actual wiki layout, but I think it
>   would be better if it was presented this way to the user. Anyway, this
>   is debatable.
>
>  * Emmanuelle has functions to read from the wiki and write to it from a
>   remote client. I am not sure how well they work, but it would be nice
>   not to require a login and rights on the server to generate patches.
>
>
>  > Is there interest to move forward with this?
>
>  There is. With Emmanuelle and Stefan van der Waalt, who has also been
>  following the project, we were considering using a webapp running with
>  turbogears to move forward. They would know better what the status is.
>
>  Congratulations for that. Let us hope you can join forces with the other
>  team working on that to bring this project to its success.
>
>  Cheers,
>
>  Gaël
>
>
> _______________________________________________
>  Numpy-discussion mailing list
>  Numpy-discussion at scipy.org
>  http://projects.scipy.org/mailman/listinfo/numpy-discussion
>