factoring out config files section
ADD
docs/source/config_files.txt
+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.*

MODIFY
docs/source/index.rst
docs/source/index.rst
@@ -13,5 +13,6 @@ Site Contents
install
usage
design
+ builder
faq
samples

MODIFY
docs/source/usage.rst
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
-------------------------------

factoring out config files section