adding initial review changes
MODIFY
docs/source/config_files.rst
docs/source/config_files.rst
@@ -4,27 +4,25 @@ Configuration Files
~~~~~~~~~~~~~~~~~~~
``repo2docker`` looks for configuration files in the repository being built
-to determine how to build it. It is philosophically similar to
-`Heroku Build Packs <https://devcenter.heroku.com/articles/buildpacks>`_.
+to determine how to build it. In general, ``repo2docker`` uses the same
+configuration files as other software installation tools,
+rather than creating new custom configuration files.
-In general, ``repo2docker`` uses the same configuration files as other software
-installation tools, rather than creating new custom configuration files.
-These files are described in :ref:`config-files`.
-
-``repo2docker`` configuration files are **composable**- you can use any number
-of them in the same repository.
+A number of ``repo2docker`` configuration files can be combined to compose more
+complex setups.
``repo2docker`` will look for configuration files in either:
-* A folder named ``binder`` in the root of the repository.
-* The root of the repository.
+* A folder named ``binder/`` in the root of the repository.
+* The root directory of the repository.
-If the folder ``binder`` is located at the top level of the repository,
- **only configuration files in the** ``binder`` **folder will be considered**.
+If the folder ``binder/`` is located at the top level of the repository,
+ **only configuration files in the** ``binder/`` **folder will be considered**.
-`binder examples <https://github.com/binder-examples>`_ contains a list of
-example repositories that can be built with ``repo2docker`` with various
-configuration files.
+The `binder examples <https://github.com/binder-examples>`_ organization on
+GitHub contains a list of sample repositories for common configurations
+that ``repo2docker`` can build with various configuration files such as
+Python and R installation in a repo.
Below is a list of supported configuration files (roughly in the order of build priority):
@@ -50,16 +48,17 @@ best-practices with Dockerfiles.
``environment.yml``
^^^^^^^^^^^^^^^^^^^
-This is a conda environment specification, that lets you install packages with conda.
+``environment.yml`` is the standard configuration file used by Anaconda, conda,
+and miniconda that lets you install Python packages.
You can also install files from pip in your ``environment.yml`` as well.
Our example `environment.yml <https://github.com/binder-examples/python-conda_pip/blob/master/environment.yml>`_
shows how one can specify a conda environment for repo2docker.
-You can also specify which Python version you are using with
-``environment.yml``. By default, ``repo2docker`` will assume you are using
-Python 3.6 with your ``environment.yml`` unless you include the version of
-Python in the file. ``conda`` supports Python versions 2.7, 3.4, 3.5, and 3.6.
-``repo2docker`` support is best with Python 2.7, 3.5, and 3.6. If you include
+You can also specify which Python version to install in your built environment
+with ``environment.yml``. By default, ``repo2docker`` **installs
+Python 3.6** with your ``environment.yml`` unless you include the version of
+Python in the file. ``conda`` supports Python versions 3.6, 3.5, 3.4, and 2.7.
+``repo2docker`` support is best with Python 3.6, 3.5, and 2.7. If you include
a Python version in a ``runtime.txt`` file in addition to your
``environment.yml``, your ``runtime.txt`` **will be ignored**.

MODIFY
docs/source/design.md
docs/source/design.md
# Design
+The repo2docker buildpacks are inspired by
+[Heroku's Build Packs](https://devcenter.heroku.com/articles/buildpacks).
+The philosophy for the repo2docker buildpacks includes:
+
+- using common configuration files for familiar installation and packaging tools
+- allowing configuration files to be combined to compose more complex setups
+- specifying default locations for configuration files
+(repo's root directory or .binder directory)
+
+
When designing `repo2docker` and adding to it in the future, the
developers are influenced by two primary use cases.
The use cases for `repo2docker` which drive most design decisions are:
@@ -9,9 +19,6 @@ The use cases for `repo2docker` which drive most design decisions are:
2. Manual image building and running the image from the command line client,
`jupyter-repo2docker`, by users interactively on their workstations
-We share our guiding design principles here. This is not an exhaustive
-list :)
-
## Deterministic output
The core of `repo2docker` can be considered a

MODIFY
docs/source/index.rst
docs/source/index.rst
@@ -4,9 +4,9 @@ jupyter-repo2docker
**jupyter-repo2docker** is a tool to build, run, and push Docker
images from source code repositories. repo2docker fetches a repo
(e.g., from GitHub or other locations) and builds a container image based
-on the specifications found in the repo.
-Optionally, it can launch a local
-Jupyter Notebook which you can use to explore it.
+on the configuration files found in the repo. It can be used to explore a
+repository locally by building and executing the constructed image of the
+repository.
Please report `Bugs <https://github.com/jupyter/repo2docker/issues>`_,
`ask questions <https://gitter.im/jupyterhub/binder>`_ or

MODIFY
docs/source/install.rst
docs/source/install.rst
@@ -49,7 +49,7 @@ That's it! For information on using ``repo2docker``, see
Windows support
---------------
-Windows support by ``repo2docker`` is still in the experimental stage.
+Windows support for ``repo2docker`` is still in the experimental stage.
An article about `using Windows and the WSL`_ (Windows Subsytem for Linux or
Bash on Windows) provides additional information about Windows and docker.
@@ -64,10 +64,10 @@ JupyterHub-ready images
`JupyterHub <https://jupyterhub.readthedocs.io/en/stable/>`_ allows multiple
users to collaborate on a shared Jupyter server. ``repo2docker`` can build
-Docker images that can be shared within a JupyterHub deployment. An example
-of using JupyterHub with ``repo2docker`` is Project Jupyter's free online
-service, `mybinder.org <https://mybinder.org>`_, which allows anyone to
-build a Docker image of a git repo online share the image with a URL.
+Docker images that can be shared within a JupyterHub deployment. For example,
+`mybinder.org <https://mybinder.org>`_ uses JupyterHub and ``repo2docker``
+to allow anyone to build a Docker image of a git repository online and
+share an executable version of the repository with a URL to the built image.
To build `JupyterHub <https://github.com/jupyterhub/jupyterhub>`_-ready
Docker images with ``repo2docker``, the version of your JupterHub deployment

MODIFY
docs/source/usage.rst
docs/source/usage.rst
@@ -14,7 +14,7 @@ order to run ``repo2docker``. For more information on installing
To ensure you can run the software in your repository, you must
-repo2docker is called with a simple command::
+repo2docker is called with this command::
jupyter-repo2docker <URL-or-path to repo>
@@ -25,11 +25,16 @@ For example, use the following to build an image of the
jupyter-repo2docker https://github.com/jakevdp/PythonDataScienceHandbook
-To build a particular branch and commit, we use the argument ``--ref`` to
+To build a particular branch and commit, use the argument ``--ref`` to
specify the ``branch-name/commit-hash``::
jupyter-repo2docker https://github.com/jakevdp/PythonDataScienceHandbook --ref master/599aa0fe3f882c0001670e676e5a8d43b92c35fc
+..tip::
+ For reproducibile research, we recommend specifying a commit-hash to
+ deterministcally build a fixed version of a repository. Not specifying a
+ commit-hash will result in the latest commit of the repository being built.
+
Building the image may take a few minutes.
During building, ``repo2docker``
@@ -45,7 +50,7 @@ specified in their configuation files and Python 3.6 is installed.
`Python Data Scinece Handbook <https://github.com/jakevdp/PythonDataScienceHandbook>`_
uses a `requirements.txt file <https://github.com/jakevdp/PythonDataScienceHandbook/blob/master/requirements.txt>`_
to specify its Python environment. ``repo2docker`` uses ``pip`` to install
-dependencies listed in the ``requirement.txt`` in image. To learn more about
+dependencies listed in the ``requirement.txt`` in the image. To learn more about
configuration files in ``repo2docker`` visit :ref:`config-files`.
When the image is built, a message will be output to your terminal::

adding initial review changes