adding example contents
MODIFY
docs/source/config_files.txt
docs/source/config_files.txt
+.. _config-files:
+
Supported configuration files
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -5,17 +7,37 @@ Below is a list of supported configuration files.
.. contents::
:local:
+ :depth: 1
``requirements.txt``
^^^^^^^^^^^^^^^^^^^^
This specifies a list of python packages that would be installed in a virtualenv (or conda environment).
+Example Contents
+````````````````
+::
+
+ numpy==1.7
+ matplotlib==2.1
+
``environment.yml``
^^^^^^^^^^^^^^^^^^^
This is a conda environment specification, that lets you install packages with conda.
+Example Contents
+````````````````
+::
+
+ channels:
+ - conda-forge
+ - defaults
+ dependencies:
+ - matplotlib
+ - pip:
+ - sphinx-gallery
+
.. important::
You must leave the ``environment.yml``'s name field empty for this
@@ -27,12 +49,26 @@ This is a conda environment specification, that lets you install packages with c
A list of debian packages that should be installed. The base image used is usually the latest released
version of Ubuntu (currently Zesty.)
+Example Contents
+````````````````
+::
+
+ cowsay
+ fortune
+
``postBuild``
^^^^^^^^^^^^^
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`.
+Example Contents
+````````````````
+::
+
+ wget <url-to-dataset>
+ python myfile.py
+
.. note::
This file must be executable to be used with ``repo2docker``. To do this,
@@ -50,6 +86,13 @@ This specifies a list of Julia packages!
Using a ``REQUIRE`` file also requires that the repository contain an
``environment.yml`` file.
+Example Contents
+````````````````
+::
+
+ PyPlot
+ Stats
+
``runtime.txt``
^^^^^^^^^^^^^^^
@@ -57,19 +100,16 @@ This allows you to control the runtime of Python. To use Python 2,
put the line ``python-2.7`` in the file. A Python 2 kernel will be installed
alongside Python 3.
-``Dockerfile``
-^^^^^^^^^^^^^^
-
-This will be treated as a regular Dockerfile and a regular Docker build will be performed. The presence
-of a Dockerfile will cause all other building behavior to not be triggered.
+Example Contents
+````````````````
+::
-Using ``repo2docker`` with a JupyterHub
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ python-2.7
-It is possible to use ``repo2docker`` in order to build JupyterHub-ready
-Docker images. In order for this to work properly, **the version of the ``jupyterhub``
-package in your git repository must match the version in your JupyterHub
-deployment**. For example, if your JupyterHub deployment runs ``jupyterhub==0.8``,
-you should put the following in ``requirements.txt`` or ``environment.yml``::
+``Dockerfile``
+^^^^^^^^^^^^^^
- jupyterhub==0.8.*
+This will be treated as a regular Dockerfile and a regular Docker build will be performed.
+The presence of a Dockerfile prevents all other build behavior.
+See the `Binder Documentation <https://mybinder.readthedocs.io/en/latest/dockerfile.html>`_ for
+best-practices with Dockerfiles.

MODIFY
docs/source/usage.rst
docs/source/usage.rst
@@ -52,8 +52,20 @@ of them in the same repository. There are a few notable rules:
For a list of repositories demonstrating various configurations,
see :ref:`samples`.
+.. *** List of all configuratoin files ***
.. include:: config_files.txt
+Using ``repo2docker`` with a JupyterHub
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+It is possible to use ``repo2docker`` in order to build JupyterHub-ready
+Docker images. In order for this to work properly, **the version of the ``jupyterhub``
+package in your git repository must match the version in your JupyterHub
+deployment**. For example, if your JupyterHub deployment runs ``jupyterhub==0.8``,
+you should put the following in ``requirements.txt`` or ``environment.yml``::
+
+ jupyterhub==0.8.*
+
Running ``repo2docker`` locally
-------------------------------

adding example contents