specification info

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,20 @@
+.. _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 and their contents
+that repo2docker uses is known as the **Reproducible Execution Environment Specification**.
+
+The goal of the REE Specification is to provide a structure that is clearly-defined and that
+can be extended to accomodate more components of a reproducible workflow.
+
+Currently, the definition of the REE Specification is the following:
+
+> Any collection of files taken from the :ref:`config_files`
+> list, placed either in the root of a folder or in a sub-folder called either ``binder/`` or ``.binder/``.
+
+In the future, the repo2docker team plans to formalize this specification into a pattern
+that can also be followed in other ways, such as by creating a JSON or YAML file.

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 git repository. It then
 performs these steps:
 
 1. Inspects the repository for :ref:`configuration files <config-files>`. These will be used to build