[SciPy-dev] [Numpy-discussion] [SciPy-user] ANN: NumPy/SciPy Documentation Marathon 2008
Stéfan van der Walt
Sat May 17 16:24:33 CDT 2008
2008/5/17 Anne Archibald <firstname.lastname@example.org>:
> * Am I supposed to be able to edit the wiki? If I go to, for example,
> and click on any of the "edit" links I am told I don't have permission
> to edit the page, in spite of having registered.
The front page of the docwiki contains all the necessary instructions:
I just need your username, then I'll add you to the EditorPage.
> * How and when are merges back from the wiki into the docstrings going
> to happen? Presumably, since any examples will become doctests, this
> will require substantial human intervention to fix all the broken
> tests (and remove instances of "shutil.deltree('/')" and the like).
For now, I shall merge the docstrings once every couple of days (at
least once a week). Each changed docstring becomes a different patch
in a bzr repository, which we host in the background. I can therefore
easily go through the changes, and decide which ones to accept.
> * Is there some special format the wiki markup needs to be in to
> ensure that the reST docstrings are properly formatted?
As long as you provide valid restructuredtext between the start and
end tags provided, your changes will be picked up correctly.
> * What fate is planned for the Numpy Example List and its progeny?
> Presumably everything in the basic Example List should be moved into
> docstrings (and therefore become doctests)? The categorized example
> list would presumably then develop links to the function documentation
> pages instead...
Those examples should definately end up in the docstrings (some of
them have, already -- see e.g. dtype). We've introduced indexing tags
in the docstrings, which should help us to generate a reference guide
organised roughly according to the categories set out in your examples
list (we haven't finalised the indexing categories, and could use some
help on that still).
More information about the Scipy-dev