Update README

README.rst

@@ -30,66 +30,93 @@ function.
 The bash scripts are layered, in the sense that they loaded in the following
 sequence:
 
-* OSX - build and test phases.  See ``multibuild/travis_osx_steps.sh``.
+OSX
+===
 
-  * multibuild/common_utils.sh
-  * multibuild/osx_utils.sh
-  * multibuild/library_builders.sh
-  * multibuild/travis_osx_steps.sh
-  * config.sh
+See ``multibuild/travis_osx_steps.sh``.
 
-* Manylinux:
+For build and test phases, these bash scripts get sourced one after the other,
+so that functions and variables defined in later scripts can overwrite
+functions and variables in earlier scripts:
 
-  * build phase (in manylinux docker container). See
-    ``multibuild/docker_build_wrap.sh``:
+* multibuild/common_utils.sh
+* multibuild/osx_utils.sh
+* multibuild/library_builders.sh
+* multibuild/travis_osx_steps.sh
+* config.sh
 
-    * multibuild/common_utils.sh
-    * multibuild/manylinux_utils.sh
-    * multibuild/library_builders.sh
-    * config.sh
+The OSX build / test and phase are on the OSX VM started by travis-ci.
+Therefore any environment variable defined in the ``.travis.yml`` or bash
+shell scripts listed above are available for your build and test.
 
-  * test phase (in Ubuntu 14.04 docker container).  See
-    ``multibuild/docker_test_wrap.sh``:
+The ``build_wheel`` function builds the wheel, and th ``install_run`` function
+installs the wheel and tests it.  Look in ``common_utils.sh`` for default
+definitions of these functions.  See below for more details.
 
-    * multibuild/common_utils.sh
-    * config.sh
+Manylinux
+=========
 
-*********************
-Environment variables
-*********************
+The build phase is in a Manylinux1 docker container, but the test phase is in a
+clean Ubuntu 14.04 container.
 
-The OSX build / test is the more straightforward of the two, because the build
-and test phase are on the same VM.  Therefore any environment variable defined
-in the ``.travis.yml`` or bash shell scripts listed above are available for
-your build and test.
+Build phase
+-----------
 
-The manylinux1 build / test is more complicated, because the build has to run
-inside a manylinux1 docker container, and the test has to run in another Ubuntu
-container.  See ``multibuild/travis_linux_steps.sh`` for the default
-invocation of docker for the build and test phases, and the environment
-variables available inside the containers.
+``multibuild/travis_linux_steps.sh`` defines the ``build_wheel`` function,
+which starts up the Manylinux1 docker container to run a wrapper script
+``multibuild/docker_build_wrap.sh``, that (within the container) sources the
+following bash scripts:
+
+* multibuild/common_utils.sh
+* multibuild/manylinux_utils.sh
+* multibuild/library_builders.sh
+* config.sh
+
+See the definition of ``build_wheel`` in ``multibuild/travis_linux_steps.sh``
+for the environment variables passed from travis-ci to the Manylinux1
+container.
+
+Once in the container, after sourcing the scripts above, the wrapper runs the
+real ``build_wheel`` function, which now comes (by default) from
+``multibuild/common_utils.sh``.
+
+Test phase
+----------
+
+Testing is in an Ubuntu 14.04 docker container - see
+``multibuild/docker_test_wrap.sh``.  ``multibuild/travis_linux_steps.sh``
+defines the ``install_run`` function, which starts up the testing docker
+container with a wrapper script ``multibuild/docker_test_wrap.sh``.  The
+wrapper script sources the following bash scripts:
+
+* multibuild/common_utils.sh
+* config.sh
+
+See ``install_run`` in ``multibuild/travis_linux_steps.sh`` for the
+environment variables passed into the container.
+
+It then (in the container) runs the real ``install_run`` command, which comes
+(by default) from ``multibuild/common_utils.sh``.
 
 *********************************
 Standard build and test functions
 *********************************
 
-The standard build command is ``build_wheel``.  This is a bash function.  By
-default it is defined in ``multibuild/common_utils.sh``, but you can override
-it in the project ``config.sh`` file (see below).  Typically, you do not
-override this function, but you define a ``pre_build`` function in
-``config.sh``, to build any libraries you need.  The default ``build_wheel``
-function will call ``pre_build``, if defined, before building the wheel.
-
-The standard test command is the bash function ``install_run``.  This is also
-defined in ``multibuild/common_utils.sh``.  Typically, you do not override
-this function, but you define a ``run_tests`` function in ``config.sh``, to
-run your tests.  ``install_run`` calls ``run_tests`` from a new temporary
-directory created in the root directory of your wheel-building repo, and
-returning a non-zero exit code for failure.
-
-See the example projects listed below for examples of less and more
-complicated build / test setups, where the complicated setups override more of
-the default implementations.
+The standard build commmand is ``build_wheel``.  This is a bash function.  By
+default the function that is run on OSX, and in the Manylinux container for
+the build phase, is defined in ``multibuild/common_utils.sh``.  You can
+override the default function in the project ``config.sh`` file (see below).
+
+The standard test command is the bash function ``install_run``.  The version
+run on OSX and in the Linux testing container is also defined in
+``multibuild/common_utils.sh``.  Typically, you do not override this function,
+but you define a ``pre_build`` function in ``config.sh``, to build any
+libraries you need, and a ``run_tests`` function, to run your tests, returning
+a non-zero error code for failure.  The default ``install_run`` implementation
+will call ``pre_build``, if defined, and then calls the ``run_tests``
+function, which you must define, probably in ``config.sh``.  See the examples
+below for examples of less and more complicateb builds, where the complicated
+builds override more of the default implementations.
 
 ********************
 To use these scripts