diff options
Diffstat (limited to 'doc/HOWTO_MERGE_WIKI_DOCS.rst.txt')
| -rw-r--r-- | doc/HOWTO_MERGE_WIKI_DOCS.rst.txt | 49 |
1 files changed, 49 insertions, 0 deletions
diff --git a/doc/HOWTO_MERGE_WIKI_DOCS.rst.txt b/doc/HOWTO_MERGE_WIKI_DOCS.rst.txt new file mode 100644 index 000000000..3431d28b0 --- /dev/null +++ b/doc/HOWTO_MERGE_WIKI_DOCS.rst.txt @@ -0,0 +1,49 @@ +======================================== +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. + +Basic steps +----------- +It works like this, both for NumPy and SciPy: + +1. Go to http://docs.scipy.org/scipy/patch/ and log in. +2. Click on "Select OK to apply" +3. Click on "Generate patch" +4. Select all the text in the browser and save as a patch. +5. Check the patch file for errors etc., edit if necessary. + Especially browse through the changes in example codes. + + .. warning:: + + 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 (``>>>`` lines, ``plot::``, and + ``doctest::``) and check that they don't try to do anything silly and + dangerous. + +6. Apply patch (typically ``patch -p1 < newdocs.patch`` from base numpy dir). + This may ask you to specify location of a few files by hand, though. +7. Run tests to see if something is broken +8. Commit + +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 + ``add_newdoc()`` in numpy/add_newdocs.py. + + 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. |