addressing carol's comments
MODIFY
README.md
README.md
[![Build Status](https://travis-ci.org/jupyter/repo2docker.svg?branch=master)](https://travis-ci.org/jupyter/repo2docker)
[![Documentation Status](https://readthedocs.org/projects/repo2docker/badge/?version=latest)](http://repo2docker.readthedocs.io/en/latest/?badge=latest)
-**jupyter-repo2docker** is a tool to build, run and push Docker images from source code repositories.
+**jupyter-repo2docker** takes as input a repository source, such as a GitHub repo. It then builds, runs, and/or pushes Docker images built from
+that source.
See the [repo2docker documentation](http://repo2docker.readthedocs.io)
for more information.
@@ -62,7 +63,8 @@ For more information on how to use ``repo2docker``, see the
## Repository specifications
-Repo2Docker looks for configuration files in the repository being built to figure out how to build it.
+Repo2Docker looks for configuration files in the source repository to
+determine how the Docker image should be built.
It is philosophically similar to [Heroku Build Packs](https://devcenter.heroku.com/articles/buildpacks).
For a list of the configuration files that ``repo2docker`` can use,

MODIFY
docs/source/faq.md
docs/source/faq.md
@@ -6,7 +6,7 @@ If you have a question & have found an answer, send a PR to add it here!
## How should I specify another version of Python 3?
-Currently the best way to do this is by using an ``environment.yaml``
+Currently the best way to do this is by using a conda ``environment.yml``
file and setting the language to whichever version of Python you like.
## Can I use repo2docker to bootstrap my own Dockerfile?

MODIFY
docs/source/install.rst
docs/source/install.rst
Installing ``repo2docker``
==========================
-Installing ``repo2docker`` is easiest using the python
-packaging index. In addition, you need to install
-`Docker <https://www.docker.com/>`_ as it is required in
-order to build images.
+1. Install `Docker <https://www.docker.com>`_ as it is required to build Docker images.
-To install ``repo2docker`` from pypi, the python packaging index::
+2. We recommend installing ``repo2docker`` with the ``pip`` tool::
- pip install jupyter-repo2docker
+ python3 -m pip install jupyter-repo2docker
-To install from source and start contributing::
+For infomation on using ``repo2docker``, see :ref:`usage`.
+
+Installing repo2docker from source code
+---------------------------------------
+
+Alternatively, you can install repo2docker from source,
+i.e. if you are contributing back to this project::
git clone https://github.com/jupyter/repo2docker.git
cd repo2docker

MODIFY
docs/source/usage.rst
docs/source/usage.rst
Using ``repo2docker``
=====================
-The core feature of repo2docker is to fetch a repo (from github or locally),
-build a container image based on the specifications found in the
-repo & optionally launch a local Jupyter Notebook you can use to explore it.
+The core functionality of repo2docker is to fetch a repo (e.g., from GitHub or
+other locations) and build 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.
This section describes the general ways in which you can use
-``repo2docker``. It covers basics in how to prepare your
-repository for building, as well as how to use ``repo2docker``
-to build repositories on your own.
+``repo2docker``, including:
+
+.. contents::
+ :depth: 1
+ :local:
+
+.. note::
See the `Frequently Asked Questions <faq.html>`_ for more info.
@@ -22,9 +26,9 @@ to determine how to build it. It is philosophically similar to
`Heroku Build Packs <https://devcenter.heroku.com/articles/buildpacks>`_.
``repo2docker`` will look for files in two places:
-* The root of the repository.
-* A folder called ``binder`` in the root of the repository (if this folder
- exists, configuration files in the root of the repository will be ignored).
+* A folder called ``binder`` in the root of the repository.
+* The root of the repository. (if a folder called ``binder`` exists in the root
+ of the repository, configuration files outside of that folder will be ignored)
.. note::
@@ -33,19 +37,20 @@ to determine how to build it. It is philosophically similar to
creating new custom configuration files.
``repodocker`` configuration files are all composable - you can use any number
-of them in the same repository, with a few notable exceptions:
+of them in the same repository. There are a few notable rules:
* ``Dockerfile``: if a Dockerfile is present in a repository, it will take precedence
over all other configuration files (which will be ignored).
-* ``environment.yaml`` with ``requirements.txt``: If both of these files are
- present, then ``environment.yaml`` will be used to build the image, **not**
+* ``environment.yml`` with ``requirements.txt``: If both of these files are
+ present, then ``environment.yml`` will be used to build the image, **not**
``requirements.txt``. If you wish to ``pip install`` packages using an
- ``environment.yaml`` file, `you should do so with the
+ ``environment.yml`` file, `you should do so with the
*pip:* key <https://conda.io/docs/user-guide/tasks/manage-environments.html#creating-an-environment-file-manually>`_.
.. note::
- For a list of sample repositories, see :ref:`samples`.
+ For a list of repositories demonstrating various configurations,
+ see :ref:`samples`.
Supported configuration files
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -62,9 +67,10 @@ This specifies a list of python packages that would be installed in a virtualenv
This is a conda environment specification, that lets you install packages with conda.
-.. note::
+.. important::
- You must leave the name of the environment empty for this to work out of the box.
+ You must leave the ``environment.yml``'s name field empty for this
+ to work out of the box.
``apt.txt``
^^^^^^^^^^^
@@ -88,13 +94,12 @@ want this to be a shell script, make sure the first line is `#!/bin/bash`.
``REQUIRE``
^^^^^^^^^^^
-This specifies a list of Julia packages! Currently only version 0.6 of Julia is supported, but more will
-be as they are released.
+This specifies a list of Julia packages!
.. note::
Using a ``REQUIRE`` file also requires that the repository contain an
- ``environment.yaml`` file.
+ ``environment.yml`` file.
``Dockerfile``
^^^^^^^^^^^^^^
@@ -109,7 +114,7 @@ It is possible to use ``repo2docker`` in order to build JupyterHub-ready
Docker images. In order for this to work properly, **the version of the ``jupyterhub``
package in your git repository must match the version in your JupyterHub
deployment**. For example, if your JupyterHub deployment runs ``jupyterhub==0.8``,
-you should put the following in ``requirements.txt`` or ``environment.yaml``::
+you should put the following in ``requirements.txt`` or ``environment.yml``::
jupyterhub==0.8.*
@@ -133,14 +138,13 @@ You can do this with the following command::
jupyter-repo2docker https://github.com/jakevdp/PythonDataScienceHandbook
-After building (it might take a while!), it should output in your terminal
-something like::
+After building (it might take a while!), it should output a message in your terminal::
Copy/paste this URL into your browser when you connect for the first time,
to login with a token:
http://0.0.0.0:36511/?token=f94f8fabb92e22f5bfab116c382b4707fc2cade56ad1ace0
-If you copy paste that URL into your browser you will see a Jupyter Notebook with the
+If you copy/paste that URL into your browser you will see a Jupyter Notebook with the
contents of the repository you have just built!
Displaying the image Dockerfile
@@ -155,8 +159,8 @@ the ``--debug`` and ``--no-build`` flags like so::
This will output the contents of the Dockerfile in your console. Note that it
will **not** build the image.
-Other build configurations
---------------------------
+Accessing help from the command line
+------------------------------------
For a list of all the build configurations at your disposal, see the
CLI help::

addressing carol's comments