updating with comments from willingc

docs/source/config_files.rst

@@ -12,14 +12,13 @@ Below is a list of supported configuration files (roughly in the order of build
 ``Dockerfile``
 ^^^^^^^^^^^^^^
 
-This will be treated as a regular Dockerfile and a regular Docker build will be performed.
-The presence of a Dockerfile takes priority over and ignores all other build behavior
-specified in other configuration files.
-
 In the majority of cases, providing your own Dockerfile is not necessary as the base
 images provide core functionality, compact image sizes, and efficient builds. We recommend
 trying the other configuration files before deciding to use your own Dockerfile.
 
+With Dockerfiles, a regular Docker build will be performed.
+**If a Dockerfile is present, all other configuration files will be ignored.**
+
 See the `Binder Documentation <https://mybinder.readthedocs.io/en/latest/dockerfile.html>`_ for
 best-practices with Dockerfiles.
 
@@ -28,14 +27,15 @@ best-practices with Dockerfiles.
 
 This is a conda environment specification, that lets you install packages with conda.
 You can also install files from pip in your ``environment.yml`` as well.
-Our example `enviornment.yml <https://github.com/binder-examples/python-conda_pip/blob/master/environment.yml>`_
+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.
 
 ``requirements.txt``
 ^^^^^^^^^^^^^^^^^^^^
 
 This specifies a list of Python packages that should be installed in your
- environment. Our `requirements.txt example <https://github.com/binder-examples/requirements/blob/master/requirements.txt>`_
+environment. Our
+`requirements.txt example <https://github.com/binder-examples/requirements/blob/master/requirements.txt>`_
 on GitHub shows a typical requirements file.
 
 ``REQUIRE``
@@ -70,9 +70,10 @@ We use ``apt.txt``, for example, to install LaTeX in our
 To install your repository like a Python package, you may include a
 ``setup.py`` file. repo2docker installs ``setup.py`` files by running
 ``pip install -e .``.
+
 While one can specify dependencies in ``setup.py``,
 repo2docker **requires configuration files such as** ``environment.yml`` or
-``requirements.txt``
+``requirements.txt`` to install dependencies during the build process.
 
 ``postBuild``
 ^^^^^^^^^^^^^
@@ -91,13 +92,14 @@ their demo for binder <https://github.com/jupyterlab/jupyterlab-demo/blob/master
 
 This allows you to control the runtime of Python or R.
 
-Adding ``python-2.7`` in the file our repository will run in a virtualenv with
+To use python-2.7: add python-2.7 in runtime.txt file.
+The repository will run in a virtualenv with
 Python 2 installed. To see a full example repository, visit our
 `Python2 example <https://github.com/binder-examples/python2_runtime/blob/master/runtime.txt>`_.
 
 repo2docker uses R libraries pinned to a specific snapshot on
 `MRAN <https://mran.microsoft.com/documents/rro/reproducibility>`_.
-You need to have a runtime.txt file that is formatted as
+You need to have a ``runtime.txt`` file that is formatted as
 ``r-<YYYY>-<MM>-<DD>``, where YYYY-MM-DD is a snapshot at MRAN that will be
 used for installing libraries.
 

docs/source/usage.rst

@@ -26,7 +26,7 @@ to determine how to build it. It is philosophically similar to
 
 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 :doc:`config-files`.
+These files are described in :ref:`config-files`.
 
 ``repo2docker`` configuration files are all **composable** - you can use any number
 of them in the same repository.
@@ -66,7 +66,7 @@ you should put the following in ``requirements.txt`` or ``environment.yml``::
 Running ``repo2docker`` locally
 -------------------------------
 
-Docker **must be running on your machine** in order to build images
+`Docker <https://docs.docker.com/>`_ **must be running on your machine** in order to build images
    with ``repo2docker``.
    For more information on installing ``repo2docker``, see :ref:`install`.