updating with comments from willingc
MODIFY
docs/source/config_files.rst
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.

MODIFY
docs/source/usage.rst
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`.

updating with comments from willingc