Merging documentation back from Doc-Wiki
This document describes how to merge back docstring edits from the pydocweb wiki (at http://docs.scipy.org/doc/) to NumPy/SciPy trunk.
It works like this, both for NumPy and SciPy:
Go to http://docs.scipy.org/scipy/patch/ and log in.
Click on "Select OK to apply"
Click on "Generate patch"
Select all the text in the browser and save as a patch.
Check the patch file for errors etc., edit if necessary. Especially browse through the changes in example codes.
The examples in the documentation will be run eg. on user's computers eventually, and we do a very limited screening of the edits on the wiki. Hence, before committing things to SVN, you absolutely MUST read through all changes to the examples (
doctest::) and check that they don't try to do anything silly and dangerous.
Apply patch (typically
patch -p1 < newdocs.patchfrom base numpy dir). This may ask you to specify location of a few files by hand, though.
Run tests to see if something is broken
Errors in patch file
Note that it is necessary to check the generated patch before trying to apply. If there are errors they are noted at the top of the file. There are two known reasons for errors:
If the error message is "source location for docstring is not known", then the function usually needs to get handled with
This may also be a sign that the docstring is generated and assigned by some automatic means, in which case the generation system may need to be revised.
If there are other messages, this may indicate a bug in the patch generation itself.