[Numpy-discussion] Question about memmap

[Gael Varoquaux]

On Wed, Jun 10, 2009 at 02:20:00AM -0500, Gökhan SEVER wrote:
>    On Wed, Jun 10, 2009 at 2:03 AM, David Goldsmith
>    <[1]d_l_goldsmith at yahoo.com> wrote:

>      My present job - and the Summer Numpy Doc Marathon - is premised on
>      making changes/additions through the Wiki; if anyone other than
>      registered developers is to be messing w/ the rst, it's news to me.  At
>      this point, someone who knows should please step in and clearly explain
>      the relationship between the Wiki and the rst (or point to the place on
>      the Wiki where this is explained).  Thanks!

>      DG

>    To me, docstring originated changes should be made on the actual source
>    codes. Since they the preliminary sources for sphinx to work on
>    integrating with rst documents under the /doc folder in the main numpy
>    trunk. There is a daily doc build system running so each change will be
>    reflected on the next build cycle.

>    Also for a developer, just doing a "svn up" will fetch the necessary
>    updated from the code-base in this case memmap.py file itself, from there
>    on it's optional whether to read docstings from the file itself or via IPy
>    or in another way. The philosophy I like in this design, a well written
>    and documented code doesn't need an additional documentation because
>    everything one needs is right in the code :)

The wiki is syncrhonised to the source. Everything that is edited in the
source ends up in the wiki, and vice versa, althought editing the same
docstring at both ends gives a conflict (which can be solved).

I tend to encourage using the wiki, because it makes it easy to document
for a non developper. Reviewing the changes is also easier.

Gaël