specification info
MODIFY
docs/source/index.rst
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

ADD
docs/source/specification.rst
+.. _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.
\ No newline at end of file

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

specification info