adding example contents

docs/source/config_files.txt

@@ -1,3 +1,5 @@
+.. _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.
 
+Example Contents
+````````````````
+::
+
+   python-2.7
+
 ``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.
-
-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.*
+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.

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
 -------------------------------