improving readmes for tests

tests/conda/binder-dir/README.rst

@@ -1,4 +0,0 @@
-Binder Directory
-----------------
-
-top-level Dockerfile will be ignored if binder directory exists.

tests/conda/requirements/README.rst

@@ -1,8 +1,9 @@
 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
 

tests/conda/simple-py2/README.rst

@@ -1,5 +1,10 @@
-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.

tests/conda/simple/README.rst

@@ -1,5 +1,7 @@
 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.

tests/dockerfile/binder-dir/README.rst

@@ -1,4 +0,0 @@
-Binder Directory
-----------------
-
-A top-level Dockerfile will be ignored if a ``binder`` directory exists.

tests/dockerfile/jupyter-stack/README.rst

@@ -1,7 +1,9 @@
 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.

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.

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.

tests/julia/pyplot/README.rst

@@ -1,7 +1,17 @@
 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.

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.

tests/venv/binder-dir/README.rst

@@ -1,4 +1,8 @@
-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.

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``.

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.
+some configuration scripts.
+
+In this example, we download and install a Jupyter Notebook extension.

tests/venv/py2/README.rst

@@ -1,5 +0,0 @@
-System - Specifying runtime environments
-----------------------------------------
-
-You can specify runtime environments (such as Python 2 or 3) with a
-``runtime.txt`` file.

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.