specification info page (#662)

specification info page

Author: betatim

docs/source/index.rst

@@ -42,6 +42,7 @@ Please report `Bugs <https://github.com/jupyter/repo2docker/issues>`_,
    :caption: Complete list of configuration files
 
    config_files
+   specification
 
 .. toctree::
    :maxdepth: 2

docs/source/specification.rst

@@ -0,0 +1,32 @@
+.. _specification:
+
+====================================================
+The Reproducible Execution Environment Specification
+====================================================
+
+repo2docker scans a repository for particular :ref:`config-files`, such
+as ``requirements.txt`` or ``REQUIRE``. The collection of files, their contents,
+and the resulting actions that repo2docker takes is known
+as the **Reproducible Execution Environment Specification** (or REES).
+
+The goal of the REES is to automate and encourage existing community best practices
+for reproducible computational environments. This includes installing pacakges using
+community-standard specification files and their corresponding tools,
+such as ``requirements.txt`` (with ``pip``), ``REQUIRE`` (with Julia), or
+``apt.txt`` (with ``apt``). While repo2docker automates the
+creation of the environment, a human should be able to look at a REES-compliant
+repository and reproduce the environment using common, clear steps without
+repo2docker software.
+
+Currently, the definition of the REE Specification is the following:
+
+    Any directory containing zero or more files from the :ref:`config-files` list is a
+    valid reproducible execution environment as defined by the REES. The
+    configuration files have to all be placed either in the root of the
+    directory, in a ``binder/`` sub-directory or a ``.binder/`` sub-directory.
+
+For example, the REES recognises ``requirements.txt`` as a valid config file.
+The file format is as defined by the ``requirements.txt`` standard of the Python
+community. A REES-compliant tool will install a Python interpreter (of unspecified version)
+and perform the equivalent action of ``pip install -r requirements.txt`` so that the
+user can afterwards run python and use the packages installed.

docs/source/usage.rst

@@ -10,7 +10,8 @@ Using ``repo2docker``
    order to run ``repo2docker``. For more information on installing
    ``repo2docker``, see :ref:`install`.
 
-``repo2docker`` is called with a URL/path to a git repository. It then
+``repo2docker`` can build a reproducible computational environment for any repository that
+follows :ref:`specification`. repo2docker is called with a URL/path to a repository. It then
 performs these steps:
 
 1. Inspects the repository for :ref:`configuration files <config-files>`. These will be used to build