factoring out config files section

docs/source/config_files.txt

@@ -0,0 +1,75 @@
+Supported configuration files
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Below is a list of supported configuration files.
+
+.. contents::
+   :local:
+
+``requirements.txt``
+^^^^^^^^^^^^^^^^^^^^
+
+This specifies a list of python packages that would be installed in a virtualenv (or conda environment).
+
+``environment.yml``
+^^^^^^^^^^^^^^^^^^^
+
+This is a conda environment specification, that lets you install packages with conda.
+
+.. important::
+
+   You must leave the ``environment.yml``'s name field empty for this
+   to work out of the box.
+
+``apt.txt``
+^^^^^^^^^^^
+
+A list of debian packages that should be installed. The base image used is usually the latest released
+version of Ubuntu (currently Zesty.)
+
+``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`.
+
+.. note::
+
+   This file must be executable to be used with ``repo2docker``. To do this,
+   run the following::
+
+     chmod +x postBuild
+
+``REQUIRE``
+^^^^^^^^^^^
+
+This specifies a list of Julia packages!
+
+.. note::
+
+   Using a ``REQUIRE`` file also requires that the repository contain an
+   ``environment.yml`` file.
+
+``runtime.txt``
+^^^^^^^^^^^^^^^
+
+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.
+
+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.*

docs/source/index.rst

@@ -13,5 +13,6 @@ Site Contents
    install
    usage
    design
+   builder
    faq
    samples

docs/source/usage.rst

@@ -52,81 +52,7 @@ of them in the same repository. There are a few notable rules:
      For a list of repositories demonstrating various configurations,
      see :ref:`samples`.
 
-Supported configuration files
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Below is a list of supported configuration files.
-
-.. contents::
-   :local:
-
-``requirements.txt``
-^^^^^^^^^^^^^^^^^^^^
-
-This specifies a list of python packages that would be installed in a virtualenv (or conda environment).
-
-``environment.yml``
-^^^^^^^^^^^^^^^^^^^
-
-This is a conda environment specification, that lets you install packages with conda.
-
-.. important::
-
-   You must leave the ``environment.yml``'s name field empty for this
-   to work out of the box.
-
-``apt.txt``
-^^^^^^^^^^^
-
-A list of debian packages that should be installed. The base image used is usually the latest released
-version of Ubuntu (currently Zesty.)
-
-``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`.
-
-.. note::
-
-   This file must be executable to be used with ``repo2docker``. To do this,
-   run the following::
-
-     chmod +x postBuild
-
-``REQUIRE``
-^^^^^^^^^^^
-
-This specifies a list of Julia packages!
-
-.. note::
-
-   Using a ``REQUIRE`` file also requires that the repository contain an
-   ``environment.yml`` file.
-
-``runtime.txt``
-^^^^^^^^^^^^^^^
-
-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.
-
-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.*
+.. include:: config_files.txt
 
 Running ``repo2docker`` locally
 -------------------------------