Skip to content

Latest commit

 

History

History
49 lines (38 loc) · 1.85 KB

HOWTO_MERGE_WIKI_DOCS.rst.txt

File metadata and controls

49 lines (38 loc) · 1.85 KB

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.