updating docs

README.md

@@ -34,6 +34,8 @@ The core feature of repo2docker is to fetch a repo (from github or locally), bui
 image based on the specifications found in the repo & optionally launch a local Jupyter Notebook
 you can use to explore it.
 
+**Note that Docker needs to be running on your machine for this to work.**
+
 Example:
 
 ```bash

docs/source/conf.py

@@ -188,19 +188,23 @@ epub_exclude_files = ['search.html']
 import os
 s = ''
 FILE_ORDER_PREFERENCE = ['System', 'Python', 'Julia', 'Docker', 'Misc']
+SKIP_FOLDERS = ['binder-dir']
 FILES_DICT = {ii: [] for ii in FILE_ORDER_PREFERENCE}
-for folder, _, files in os.walk(os.path.join('..', '..', 'tests')):
-    if 'README.rst' not in files:
+for root, _, files in os.walk(os.path.join('..', '..', 'tests')):
+    depth = len(root.split('/')) - 3
+    if 'README.rst' not in files or depth > 2:
+        continue
+    if any(folder in root for folder in SKIP_FOLDERS):
         continue
     header = files.pop(files.index('README.rst'))
-    with open(os.path.join(folder, header), 'r') as ff:
+    with open(os.path.join(root, header), 'r') as ff:
         this_s = ff.read() + '\n'
         title = this_s.split('\n')[0]
     for ifile in files:
         filename = os.path.basename(ifile)
         if filename == 'verify':
             continue
-        with open(os.path.join(folder, ifile), 'r') as ff:
+        with open(os.path.join(root, ifile), 'r') as ff:
             lines = ff.readlines()
         lines = ['   ' + line for line in lines]
         this_s += 'File: ``{}``\n{}\n\n**Contents**::\n\n'.format(
@@ -209,7 +213,7 @@ for folder, _, files in os.walk(os.path.join('..', '..', 'tests')):
         this_s += '\n\n'
         usename = [ii for ii in FILE_ORDER_PREFERENCE if ii in title]
         usename = 'Misc' if len(usename) == 0 else usename[0]
-        FILES_DICT[usename].append(this_s)
+    FILES_DICT[usename].append(this_s)
 for key in FILE_ORDER_PREFERENCE:
     for istring in FILES_DICT[key]:
         s += istring

docs/source/samples.rst

@@ -4,4 +4,11 @@ Sample build files
 There are many options for specifying your environment with ``repo2docker``.
 The following sections describe a few samples to get you started.
 
+.. note::
+
+  These files must be in the root of your repository, or in a folder called
+  ``binder`` that is in the root of your repository. If you include a folder
+  called ``binder`` in the root of your repository, then all build files *not*
+  inside this folder will be ignored.
+
 .. include:: test_file_text.txt

repo2docker/detectors.py

@@ -121,6 +121,7 @@ RUN ./{{ s }}
 {% endif -%}
 """
 
+DOC_URL = "http://repo2docker.readthedocs.io/en/latest/samples.html"
 
 class BuildPack(LoggingConfigurable):
     """
@@ -466,7 +467,8 @@ class BaseImage(BuildPack):
         post_build = self.binder_path('postBuild')
         if os.path.exists(post_build):
             if not stat.S_IXUSR & os.stat(post_build).st_mode:
-                raise ValueError("%s is not executable" % post_build)
+                raise ValueError("%s is not executable, see %s for help." % (
+                                 post_build, DOC_URL+'#system-post-build-scripts'))
             return [post_build]
         return []
 

tests/dockerfile/binder-dir/README.rst

@@ -1,4 +1,4 @@
 Binder Directory
 ----------------
 
-top-level Dockerfile will be ignored if binder directory exists.
+A top-level Dockerfile will be ignored if a ``binder`` directory exists.

tests/venv/postBuild/README.rst

@@ -5,3 +5,10 @@ It is possible to run scripts after you've built the environment specified in
 your other files. This could be used to, for example, download data or run
 some configuration scripts. For example, this will download and install a
 Jupyter extension.
+
+.. note::
+
+   This file needs to be executable in order to work with ``repo2docker``. The
+   easiest way to do this is to run the following command with ``git``::
+
+       git update-index --chmod=+x postBuild