adding initial review changes

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

docs/source/design.md

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

docs/source/faq.md

@@ -1,7 +1,7 @@
 # Frequently Asked Questions (FAQ)
 
 A collection of frequently asked questions with answers. If you have a question
-and  have found an answer, send a PR to add it here!
+and have found an answer, send a PR to add it here!
 
 ## How should I specify another version of Python 3?
 

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

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

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::