Split out tests, tweak docs, and a style change

This splits out the test for the launch script from the postBuild script
test. Makes some adjustments to the documentation of the launch script
functionality and applies some pythonista styling.

docs/source/config_files.rst

@@ -117,7 +117,7 @@ repo2docker **requires configuration files such as** ``environment.yml`` or
 A script that can contain arbitrary commands to be run after the whole repository has been built. If you
 want this to be a shell script, make sure the first line is ```#!/bin/bash``.
 
-An example usecase of ``postBuild`` file is JupyterLab's demo on mybinder.org.
+An example use-case of ``postBuild`` file is JupyterLab's demo on mybinder.org.
 It uses a ``postBuild`` file in a folder called ``binder`` to `prepare
 their demo for binder <https://github.com/jupyterlab/jupyterlab-demo/blob/master/binder/postBuild>`_.
 
@@ -126,12 +126,18 @@ their demo for binder <https://github.com/jupyterlab/jupyterlab-demo/blob/master
 ``start``
 ^^^^^^^^^
 
-A script that can contain arbitrary commands to be run at runtime (as an
+A script that can contain simple commands to be run at runtime (as an
 `ENTRYPOINT <https://docs.docker.com/engine/reference/builder/#entrypoint>`
 to the docker container). If you want this to be a shell script, make sure the
 first line is ```#!/bin/bash``. The last line must be ```exec "$@"```
 equivalent.
 
+Use this to set environment variables that software installed in your container
+expects to be set. This script is executed each time your binder is started and
+should at most take a few seconds to run.
+
+If you only need to run things once during the build phase use :ref:`postBuild`.
+
 .. TODO: Discuss runtime limits, best practices, etc.
    Also, point to an example.
 

repo2docker/buildpacks/base.py

@@ -132,7 +132,7 @@ RUN ./{{ s }}
 {% endif -%}
 
 # Add start script
-{% if start_script -%}
+{% if start_script is not none -%}
 RUN chmod +x "{{ start_script }}"
 ENTRYPOINT ["{{ start_script }}"]
 {% endif -%}
@@ -331,8 +331,8 @@ class BuildPack:
         """
         An ordered list of executable scripts to execute after build.
 
-        Is run as a non-root user, and must be executable. Used for doing
-        things that are currently not supported by other means!
+        Is run as a non-root user, and must be executable. Used for performing
+        build time steps that can not be perfomed with standard tools.
 
         The scripts should be as deterministic as possible - running it twice
         should not produce different results!
@@ -341,18 +341,18 @@ class BuildPack:
 
     def get_start_script(self):
         """
-        An ordered list of executable scripts to be executated at runtime.
-        These scripts are added as an `ENTRYPOINT` to the container.
+        The path to a script to be executated at container start up.
 
-        Is run as a non-root user, and must be executable. Used for doing
-        things that are currently not supported by other means and need to be
-        applied at runtime (set environment variables).
+        This script is added as the `ENTRYPOINT` to the container.
 
-        The scripts should be as deterministic as possible - running it twice
+        It is run as a non-root user, and must be executable. Used for performing
+        run time steps that can not be perfomed with standard tools. For example
+        setting environment variables for your repository.
+
+        The script should be as deterministic as possible - running it twice
         should not produce different results.
-
         """
-        return ''
+        return None
 
     def binder_path(self, path):
         """Locate a file"""
@@ -546,4 +546,4 @@ class BaseImage(BuildPack):
         start = self.binder_path('start')
         if os.path.exists(start):
             return start
-        return ''
+        return None

tests/venv/start/start-script/README.rst

@@ -0,0 +1,8 @@
+System - launch scripts
+-----------------------
+
+It is possible to run `start` scripts before your notebook server starts.
+This is useful to set environment variables or perform last minute
+configurations.
+
+In this example we set a environment variable in the `start` script.

tests/venv/start/start-script/verify

@@ -0,0 +1,8 @@
+#!/bin/bash
+set -euo pipefail
+
+if [ "$TEST_START_VAR" != "var is set" ]
+then
+  echo "TEST_START_VAR is not set"
+  exit 1
+fi