From b20438bd593ecf1a2cf3473272c4ccbf2481cc7d Mon Sep 17 00:00:00 2001 From: Chris Holdgraf Date: Thu, 2 May 2019 15:58:58 -0700 Subject: [PATCH 1/3] specification info --- docs/source/index.rst | 1 + docs/source/specification.rst | 20 ++++++++++++++++++++ docs/source/usage.rst | 3 ++- 3 files changed, 23 insertions(+), 1 deletion(-) create mode 100644 docs/source/specification.rst diff --git a/docs/source/index.rst b/docs/source/index.rst index f150f352..d5aff875 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -42,6 +42,7 @@ Please report `Bugs `_, :caption: Complete list of configuration files config_files + specification .. toctree:: :maxdepth: 2 diff --git a/docs/source/specification.rst b/docs/source/specification.rst new file mode 100644 index 00000000..2c357c2b --- /dev/null +++ b/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. \ No newline at end of file diff --git a/docs/source/usage.rst b/docs/source/usage.rst index 449af33e..c21f7f4b 100644 --- a/docs/source/usage.rst +++ b/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 `. These will be used to build From 1c66925090f5f3553ce81754ddcccde1aba87369 Mon Sep 17 00:00:00 2001 From: Chris Holdgraf Date: Fri, 3 May 2019 09:33:37 -0700 Subject: [PATCH 2/3] 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. From f86a06d4ba283101aad01b8863e00c0ab2c95162 Mon Sep 17 00:00:00 2001 From: Chris Holdgraf Date: Fri, 3 May 2019 15:08:48 -0700 Subject: [PATCH 3/3] tim comments in specification doc --- docs/source/specification.rst | 14 ++++++++------ docs/source/usage.rst | 2 +- 2 files changed, 9 insertions(+), 7 deletions(-) diff --git a/docs/source/specification.rst b/docs/source/specification.rst index 789ccf62..a3fef2d3 100644 --- a/docs/source/specification.rst +++ b/docs/source/specification.rst @@ -10,18 +10,20 @@ 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 -community-standard specification files such as ``requirements.txt`` or ``REQUIRE`` using -standard tools such as ``pip`` or ``conda`` or ``apt``. While repo2docker automates the +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 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 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 diff --git a/docs/source/usage.rst b/docs/source/usage.rst index c21f7f4b..a4360760 100644 --- a/docs/source/usage.rst +++ b/docs/source/usage.rst @@ -11,7 +11,7 @@ Using ``repo2docker`` ``repo2docker``, see :ref:`install`. ``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 +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 `. These will be used to build