blob: 3431d28b0a116c278ff243ad55f7f84b579010b8 (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
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.
|
