improving readmes for tests
DELETE
tests/conda/binder-dir/README.rst
-Binder Directory
-----------------
-
-top-level Dockerfile will be ignored if binder directory exists.

MODIFY
tests/conda/requirements/README.rst
tests/conda/requirements/README.rst
Conda - Mixed Requirements
--------------------------
-An ``environment.yml`` takes precedence over ``requirements.txt``.
-To install Python packages into a conda environment with pip, use the ``pip`` key in ``environment.yml``:
+An ``environment.yml`` file takes precedence over ``requirements.txt``.
+To install Python packages into a conda environment with pip, use the
+``pip`` key in ``environment.yml``:
.. sourcecode:: yaml

MODIFY
tests/conda/simple-py2/README.rst
tests/conda/simple-py2/README.rst
-Conda Environment
------------------
+Conda Environment and Python 2
+------------------------------
-Conda environments files may allow for more complex builds and dependencies. You
-can specify them in the standard `environment.yml` files.
+``environment.yml`` is the standard method for defining environments with the
+Anaconda (conda) distribution. Conda environment files may allow for more
+complex builds and dependencies than are possible with a single
+``requirements.txt`` file.
+
+This example shows how to define a Python 2 environment with Anaconda. You can
+define any version of Python that Anaconda supports.

MODIFY
tests/conda/simple/README.rst
tests/conda/simple/README.rst
Conda Environment
-----------------
-Conda environments files may allow for more complex builds and dependencies. You
-can specify them in the standard `environment.yml` files.
+``environment.yml`` is the standard method for defining environments with the
+Anaconda (conda) distribution. Conda environment files may allow for more
+complex builds and dependencies than are possible with a single
+``requirements.txt`` file.

DELETE
tests/dockerfile/binder-dir/README.rst
-Binder Directory
-----------------
-
-A top-level Dockerfile will be ignored if a ``binder`` directory exists.

MODIFY
tests/dockerfile/jupyter-stack/README.rst
tests/dockerfile/jupyter-stack/README.rst
Docker - Specifying dependencies
--------------------------------
-You can specify dependencies with Dockerfiles, which may be more flexible
-in running non-standard code. We recommend sourcing your Dockerfile from
-one of the Jupyter base images. In this case, we use a stripped-down image
-that has minimal dependencies installed.
+You can use a Dockerfiles to use a "source" Docker image that has a pre-built
+environment. This may be more flexible in running non-standard code.
+
+We recommend sourcing your Dockerfile from one of the Jupyter base images
+to ensure that it works with JupyterHub. In this case, we use a stripped-down
+image that has minimal dependencies installed.

MODIFY
tests/dockerfile/legacy/README.rst
tests/dockerfile/legacy/README.rst
@@ -4,4 +4,5 @@ Docker - Legacy Dockerfiles
This demonstrates the Dockerfile syntax that was often found in the first
version of Binder. It sources the ``andrewosh`` Docker image, which
contained many different dependencies, then installs Julia. We encourage
-users to source one of the Jupyter base images as they are more streamlined.
+users to source one of the Jupyter base images as they are more streamlined,
+reliable, and efficient.

MODIFY
tests/dockerfile/simple/README.rst
tests/dockerfile/simple/README.rst
@@ -2,6 +2,8 @@ Docker - Running scripts
------------------------
It's possible to run scripts using Docker in your build. In this case, we run
-a simple shell script after installing dependencies. However, we recommend
-that you see if it's possible to accomplish what you want using ``apt`` and
-``postInstall`` files, and use Dockerfiles only when necessary.
+a simple shell script after installing dependencies.
+
+While it's possible to run code with Dockerfiles, we recommend
+that try accomplishing the same thing with ``apt.txt`` and
+``postBuild`` files. Only use Dockerfiles when necessary.

MODIFY
tests/julia/pyplot/README.rst
tests/julia/pyplot/README.rst
Julia - REQUIRE
---------------
-The simplest way to specify dependencies in Julia, a REQUIRE file simply
-lists the names of packages. Each one will be installed but not pre-compiled.
-In this case, we also specify python dependencies with an ``environment.yml``
-file.
+To specify dependencies in Julia, include a REQUIRE file that lists the names
+of packages you'd like to be installed. For example:
+
+```
+PyPlot
+IJulia
+DataFrames
+```
+
+Each one will be installed but **not** pre-compiled. If you'd like to
+pre-compile your Julia packages, consider using a ``postBuild`` file.
+
+Note that this example also specifies Python dependencies with an
+``environment.yml`` file.

MODIFY
tests/venv/apt-packages/README.rst
tests/venv/apt-packages/README.rst
@@ -2,4 +2,9 @@ System - APT Packages
---------------------
It is possible to install packages using the Shell with the ``apt.txt`` file.
-In this case we install ``gfortran`` which does not have an easy Python install.
+This allows you to install libraries that aren't easy to install with package
+managers such as ``pip`` or ``conda``. This can be useful if you must install
+something that depends on a low-level library already being present.
+
+In this case we install ``gfortran``, which does not have an easy Python
+install.

MODIFY
tests/venv/binder-dir/README.rst
tests/venv/binder-dir/README.rst
-Binder Directory
-----------------
+Binder Directory for configuration files
+----------------------------------------
-top-level environment.yml will be ignored if binder directory exists.
+If a directory called ``binder/`` exists in the top level of the repository,
+then all configuration files that are **not** in ``binder/`` will be ignored.
+This is particularly useful if you have a ``Dockerfile`` defined in a
+repository, but don't want ``repo2docker``to use it for building the
+environment.

MODIFY
tests/venv/numpy/README.rst
tests/venv/numpy/README.rst
@@ -2,4 +2,4 @@ Python - Requirements.txt
-------------------------
The simplest way to specify Python packages is with a ``requirements.txt`` file
-that is compatible with ``pip install``.
+that is compatible with ``pip install``. In this case, we install ``numpy``.

MODIFY
tests/venv/postBuild/README.rst
tests/venv/postBuild/README.rst
@@ -3,5 +3,6 @@ System - Post-build scripts
It is possible to run scripts after you've built the environment specified in
your other files. This could be used to, for example, download data or run
-some configuration scripts. For example, this will download and install a
-Jupyter extension.
\ No newline at end of file
+some configuration scripts.
+
+In this example, we download and install a Jupyter Notebook extension.

DELETE
tests/venv/py2/README.rst
-System - Specifying runtime environments
-----------------------------------------
-
-You can specify runtime environments (such as Python 2 or 3) with a
-``runtime.txt`` file.

MODIFY
tests/venv/py3/README.rst
tests/venv/py3/README.rst
@@ -2,8 +2,19 @@ System - Specifying runtime environments
----------------------------------------
You can specify runtime environments (such as Python 2 or 3) with a
-``runtime.txt`` file.
+``runtime.txt`` file. To do so, include a line of the following form in
+your ``runtime.txt`` file:
+
+```
+python-N
+```
+
+Where ``N`` is either ``2`` or ``3``. If ``N==2``, Python 2.7 will be used.
+If ``N==3``, Python 3.6 will be used.
This is an example that selects Python 3. Currently you can not use
-this to select a sepcific version of Python 3 (e.g. 3.4 vs 3.6). If you
+this to select a specific version of Python 3 (e.g. 3.4 vs 3.6). If you
need this level of control we recommend you use a `environment.yml`.
+
+Note that you can also install Python environments using the Anaconda
+distribution by using an ``environment.yml`` file.

improving readmes for tests