merging refs/remotes/origin/master into HEAD

DEV_README.txt

@@ -3,7 +3,7 @@ available.
 
 We have a few simple rules: 
 
-   * try hard to keep the SVN repository in a buildable state and to not
+   * try hard to keep the Git repository in a buildable state and to not
      indiscriminately muck with what others have contributed.
 
    * Simple changes (including bug fixes) and obvious improvements are 
@@ -14,6 +14,6 @@ We have a few simple rules:
    * Please add meaningful comments when you check changes in.  These
      comments form the basis of the change-log.  
 
-   * Add unit tests to excercise new code, and regression tests
+   * Add unit tests to exercise new code, and regression tests
      whenever you fix a bug.
 

doc/HOWTO_BUILD_DOCS.txt

@@ -3,9 +3,7 @@ Building the NumPy API and reference docs
 =========================================
 
 We currently use Sphinx_ for generating the API and reference
-documentation for Numpy.  You will need Sphinx 0.5 or newer. Sphinx's
-current development version also works as of now (2009-06-24), and
-using it is recommended though not required.
+documentation for Numpy.  You will need Sphinx 1.0.1 or newer.
 
 If you only want to get the documentation, note that pre-built
 versions can be found at

doc/HOWTO_DOCUMENT.txt

@@ -333,6 +333,13 @@ The sections of the docstring are:
      >>> np.add([1, 2], [3, 4])
      array([4, 6])
 
+   For tests with a result that is random or platform-dependent, mark the
+   output as such::
+
+     >>> import numpy.random
+     >>> np.random.rand(2)
+     array([ 0.35773152,  0.38568979])  #random     
+
    You can run examples using::
 
      >>> np.test(doctests=True)

doc/Makefile

@@ -11,15 +11,13 @@ PAPER         =
 
 FILES=
 
-NEED_AUTOSUMMARY = $(shell $(PYTHON) -c 'import sphinx; print sphinx.__version__ < "0.7" and "1" or ""')
-
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
 ALLSPHINXOPTS   = -d build/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
 
 .PHONY: help clean html web pickle htmlhelp latex changes linkcheck \
-        dist dist-build
+        dist dist-build gitwash-update
 
 #------------------------------------------------------------------------------
 
@@ -33,10 +31,18 @@ help:
 	@echo "  linkcheck to check all external links for integrity"
 	@echo "  dist PYVER=... to make a distribution-ready tree"
 	@echo "  upload USER=...  to upload results to docs.scipy.org"
+	@echo "  gitwash-update GITWASH=path/to/gitwash  update gitwash developer docs"
 
 clean:
 	-rm -rf build/* source/reference/generated
 
+gitwash-update:
+	rm -rf source/dev/gitwash
+	install -d source/dev/gitwash
+	python $(GITWASH)/gitwash_dumper.py source/dev NumPy \
+	    --repo-name=numpy \
+	    --github-user=numpy
+	cat source/dev/gitwash_links.txt >> source/dev/gitwash/git_links.inc
 
 #------------------------------------------------------------------------------
 # Automated generation of all documents
@@ -99,11 +105,6 @@ dist-build:
 generate: build/generate-stamp
 build/generate-stamp: $(wildcard source/reference/*.rst)
 	mkdir -p build
-ifeq ($(NEED_AUTOSUMMARY),1)
-	$(PYTHON) \
-		./sphinxext/autosummary_generate.py source/reference/*.rst \
-		-p dump.xml -o source/reference/generated 
-endif
 	touch build/generate-stamp
 
 html: generate

doc/TESTS.txt

@@ -41,7 +41,6 @@ follows::
   >>> import numpy
   >>> numpy.test()
 
-
 The test method may take two or more arguments; the first is a string
 label specifying what should be tested and the second is an integer
 giving the level of output verbosity. See the docstring for numpy.test
@@ -86,25 +85,27 @@ module called ``test_yyy.py``.  If you only need to test one aspect of
 ``zzz``, you can simply add a test function::
 
   def test_zzz():
-      assert zzz() == 'Hello from zzz'
+      assert_(zzz() == 'Hello from zzz')
 
 More often, we need to group a number of tests together, so we create
 a test class::
 
-  from numpy.testing import *
+  from numpy.testing import assert_, assert_raises
 
   # import xxx symbols
   from scipy.xxx.yyy import zzz
 
   class TestZzz:
       def test_simple(self):
-          assert zzz() == 'Hello from zzz'
+          assert_(zzz() == 'Hello from zzz')
 
       def test_invalid_parameter(self):
           assert_raises(...)
 
-Within these test methods, ``assert()`` is used to test whether a
-certain assumption is valid. If the assert fails, the test fails.
+Within these test methods, ``assert_()`` and related functions are used to test
+whether a certain assumption is valid. If the assertion fails, the test fails.
+Note that the Python builtin ``assert`` should not be used, because it is
+stripped during compilation with ``-O``.
 
 Sometimes it is convenient to run ``test_yyy.py`` by itself, so we add
 
@@ -124,7 +125,7 @@ therefore reserved for a full ``scipy.test(label='full')`` run, you
 can label it with a nose decorator::
 
   # numpy.testing module includes 'import decorators as dec'
-  from numpy.testing import *
+  from numpy.testing import dec, assert_
 
   @dec.slow
   def test_big(self):
@@ -135,7 +136,7 @@ Similarly for methods::
   class test_zzz:
       @dec.slow
       def test_simple(self):
-          assert zzz() == 'Hello from zzz'
+          assert_(zzz() == 'Hello from zzz')
 
 Easier setup and teardown functions / methods
 ---------------------------------------------
@@ -156,7 +157,9 @@ You can add setup and teardown functions to functions and methods with
 nose decorators::
 
   import nose
-  from numpy.testing import *
+  # import all functions from numpy.testing that are needed
+  from numpy.testing import assert_, assert_array_almost_equal
+
   def setup_func():
       """A trivial setup function."""
       global helpful_variable
@@ -185,7 +188,7 @@ with test generators::
 
   def check_even(n, nn):
       """A check function to be used in a test generator."""
-      assert n % 2 == 0 or nn % 2 == 0
+      assert_(n % 2 == 0 or nn % 2 == 0)
 
   def test_evens():
       for i in range(0,4,2):
@@ -306,13 +309,13 @@ from one in `numpy/linalg/tests/test_linalg.py
       def do(self, a, b):
           x = linalg.solve(a, b)
           assert_almost_equal(b, dot(a, x))
-          assert imply(isinstance(b, matrix), isinstance(x, matrix))
+          assert_(imply(isinstance(b, matrix), isinstance(x, matrix)))
 
   class TestInv(LinalgTestCase):
       def do(self, a, b):
           a_inv = linalg.inv(a)
           assert_almost_equal(dot(a, a_inv), identity(asarray(a).shape[0]))
-          assert imply(isinstance(a, matrix), isinstance(a_inv, matrix))
+          assert_(imply(isinstance(a, matrix), isinstance(a_inv, matrix)))
 
 In this case, we wanted to test solving a linear algebra problem using
 matrices of several data types, using ``linalg.solve`` and
@@ -329,7 +332,7 @@ The decorators from numpy.testing.dec can be used to do this.
 
 To skip a test, simply use ``skipif``::
 
-  from numpy.testing import *
+  from numpy.testing import dec
 
   @dec.skipif(SkipMyTest, "Skipping this test because...")
   def test_something(foo):
@@ -340,7 +343,7 @@ and the message in verbose test output is the second argument given to
 ``skipif``.  Similarly, a test can be marked as a known failure by
 using ``knownfailureif``::
 
-  from numpy.testing import *
+  from numpy.testing import dec
 
   @dec.knownfailureif(MyTestFails, "This test is known to fail because...")
   def test_something_else(foo):