From 1c66925090f5f3553ce81754ddcccde1aba87369 Mon Sep 17 00:00:00 2001 From: Chris Holdgraf Date: Fri, 3 May 2019 09:33:37 -0700 Subject: [PATCH] updates per comments --- docs/source/specification.rst | 28 +++++++++++++++++++--------- 1 file changed, 19 insertions(+), 9 deletions(-) diff --git a/docs/source/specification.rst b/docs/source/specification.rst index 2c357c2b..789ccf62 100644 --- a/docs/source/specification.rst +++ b/docs/source/specification.rst @@ -4,17 +4,27 @@ 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**. +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 REE Specification is to provide a structure that is clearly-defined and that -can be extended to accomodate more components of a reproducible workflow. +The goal of the REES is to automate and encourage existing community best practices +for reproducible computational environments. This includes installing +community-standard specification files such as ``requirements.txt`` or ``REQUIRE`` using +standard tools such as ``pip`` or ``conda`` or ``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 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/``. + 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 +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.