DOC: rename ReST files under doc/ from *.txt to *.rst.txt, so they render on github.

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.