From 30b37a35e484ef8a2437ccf287b24ca26651e36f Mon Sep 17 00:00:00 2001 From: Chris Holdgraf Date: Tue, 24 Apr 2018 17:14:01 -0700 Subject: [PATCH] improving readmes for tests --- tests/conda/binder-dir/README.rst | 4 ---- tests/conda/requirements/README.rst | 5 +++-- tests/conda/simple-py2/README.rst | 13 +++++++++---- tests/conda/simple/README.rst | 6 ++++-- tests/dockerfile/binder-dir/README.rst | 4 ---- tests/dockerfile/jupyter-stack/README.rst | 10 ++++++---- tests/dockerfile/legacy/README.rst | 3 ++- tests/dockerfile/simple/README.rst | 8 +++++--- tests/julia/pyplot/README.rst | 18 ++++++++++++++---- tests/venv/apt-packages/README.rst | 7 ++++++- tests/venv/binder-dir/README.rst | 10 +++++++--- tests/venv/numpy/README.rst | 2 +- tests/venv/postBuild/README.rst | 5 +++-- tests/venv/py2/README.rst | 5 ----- tests/venv/py3/README.rst | 15 +++++++++++++-- 15 files changed, 73 insertions(+), 42 deletions(-) delete mode 100644 tests/conda/binder-dir/README.rst delete mode 100644 tests/dockerfile/binder-dir/README.rst delete mode 100644 tests/venv/py2/README.rst diff --git a/tests/conda/binder-dir/README.rst b/tests/conda/binder-dir/README.rst deleted file mode 100644 index a2ef2871..00000000 --- a/tests/conda/binder-dir/README.rst +++ /dev/null @@ -1,4 +0,0 @@ -Binder Directory ----------------- - -top-level Dockerfile will be ignored if binder directory exists. diff --git a/tests/conda/requirements/README.rst b/tests/conda/requirements/README.rst index b8121f20..7fb93d74 100644 --- a/tests/conda/requirements/README.rst +++ b/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 diff --git a/tests/conda/simple-py2/README.rst b/tests/conda/simple-py2/README.rst index 12fa744b..7e44b004 100644 --- a/tests/conda/simple-py2/README.rst +++ b/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. diff --git a/tests/conda/simple/README.rst b/tests/conda/simple/README.rst index 51084708..9758affb 100644 --- a/tests/conda/simple/README.rst +++ b/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. diff --git a/tests/dockerfile/binder-dir/README.rst b/tests/dockerfile/binder-dir/README.rst deleted file mode 100644 index d68030df..00000000 --- a/tests/dockerfile/binder-dir/README.rst +++ /dev/null @@ -1,4 +0,0 @@ -Binder Directory ----------------- - -A top-level Dockerfile will be ignored if a ``binder`` directory exists. diff --git a/tests/dockerfile/jupyter-stack/README.rst b/tests/dockerfile/jupyter-stack/README.rst index a42bbf09..e2cd4aa1 100644 --- a/tests/dockerfile/jupyter-stack/README.rst +++ b/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. diff --git a/tests/dockerfile/legacy/README.rst b/tests/dockerfile/legacy/README.rst index 4fbf441b..0e070d00 100644 --- a/tests/dockerfile/legacy/README.rst +++ b/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. diff --git a/tests/dockerfile/simple/README.rst b/tests/dockerfile/simple/README.rst index 2b11ee48..120898e4 100644 --- a/tests/dockerfile/simple/README.rst +++ b/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. diff --git a/tests/julia/pyplot/README.rst b/tests/julia/pyplot/README.rst index 87568848..2c28689c 100644 --- a/tests/julia/pyplot/README.rst +++ b/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. diff --git a/tests/venv/apt-packages/README.rst b/tests/venv/apt-packages/README.rst index a37d88b7..b7c14f97 100644 --- a/tests/venv/apt-packages/README.rst +++ b/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. diff --git a/tests/venv/binder-dir/README.rst b/tests/venv/binder-dir/README.rst index 618a6692..b98cc76f 100644 --- a/tests/venv/binder-dir/README.rst +++ b/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. diff --git a/tests/venv/numpy/README.rst b/tests/venv/numpy/README.rst index 71bae4f5..46443854 100644 --- a/tests/venv/numpy/README.rst +++ b/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``. diff --git a/tests/venv/postBuild/README.rst b/tests/venv/postBuild/README.rst index f57e58d8..1a9851f3 100644 --- a/tests/venv/postBuild/README.rst +++ b/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. diff --git a/tests/venv/py2/README.rst b/tests/venv/py2/README.rst deleted file mode 100644 index 8c125c92..00000000 --- a/tests/venv/py2/README.rst +++ /dev/null @@ -1,5 +0,0 @@ -System - Specifying runtime environments ----------------------------------------- - -You can specify runtime environments (such as Python 2 or 3) with a -``runtime.txt`` file. diff --git a/tests/venv/py3/README.rst b/tests/venv/py3/README.rst index f55f95af..81961f7b 100644 --- a/tests/venv/py3/README.rst +++ b/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.