Update documentation with more cross references

Author: betatim

docs/source/config_files.rst

@@ -23,7 +23,7 @@ Below is a list of supported configuration files (roughly in the order of build
    :local:
    :depth: 1
 
-.. _environment-yml:
+.. _environment.yml:
 
 ``environment.yml`` - Install a Python environment
 ==================================================
@@ -50,6 +50,7 @@ Python in the file.  ``conda`` supports Python versions 3.6, 3.5, 3.4, and 2.7.
    If you include a Python version in a ``runtime.txt`` file in addition to your
    ``environment.yml``, your ``runtime.txt`` will be ignored.
 
+.. _requirements.txt:
 
 ``requirements.txt`` - Install a Python environment
 ===================================================
@@ -67,6 +68,7 @@ To install your repository like a Python package, you may include a
 ``setup.py`` file. repo2docker installs ``setup.py`` files by running
 ``pip install -e .``.
 
+.. _REQUIRE:
 
 ``REQUIRE`` - Install a Julia environment
 =========================================

docs/source/faq.rst

@@ -17,11 +17,14 @@ What versions of Python (or R or Julia...) are supported?
 Python
 ~~~~~~
 
-Repo2docker officially supports the following versions of Python (specified in environment.yml or runtime.txt):
+Repo2docker officially supports the following versions of Python
+(specified in your :ref:`environment.yml <environment.yml>` or
+:ref:`runtime.txt <runtime.txt>` file):
 
 - 3.7 (added in 0.7)
 - 3.6 (default)
 - 3.5
+- 2.7
 
 Additional versions may work, as long as the
 `base environment <https://github.com/jupyter/repo2docker/blob/master/repo2docker/buildpacks/conda/environment.yml>`_
@@ -31,14 +34,15 @@ in the base environment is not packaged for your Python,
 either because the version of the package is too new and your chosen Python is too old,
 or vice versa.
 
-Additionally, if Python 2.7 is specified,
-a separate environment for the kernel will be installed with Python 2.
-The notebook server will run in the default Python 3.6 environment.
+I Python 2.7 is specified, a separate environment for the kernel will be
+installed with Python 2. The notebook server will run in the default Python 3.6
+environment.
 
 Julia
 ~~~~~
 
-The following versions of Julia are supported (specified in REQUIRE):
+The following versions of Julia are supported (specified in the
+:ref:`REQUIRE <REQUIRE>` configuration file):
 
 - 1.0 (added in 0.7)
 - 0.7 (added in 0.7)
@@ -61,7 +65,11 @@ a subsequent build step.)
 How do I set environment variables?
 -----------------------------------
 
-Use the ``-e`` or ``--env`` flag for each variable that you want to define.
+To configure environment variables for all users of a repository use the
+:ref:`start <start>` configuration file.
+
+When running repo2docker locally you can use the ``-e`` or ``--env`` command-line
+flag for each variable that you want to define.
 
 For example ``jupyter-repo2docker -e VAR1=val1 -e VAR2=val2 ...``
 

docs/source/index.rst

@@ -5,12 +5,15 @@ jupyter-repo2docker
 images from source code repositories** that run via a Jupyter server.
 
 ``repo2docker`` fetches a repository
-(e.g., from GitHub or other locations) and builds a container image
+(from GitHub, GitLab or other locations) and builds a container image
 based on the configuration files found in the repository. It can be
 used to explore a repository locally by building and executing the
 constructed image of the repository, or as a means of building images that
 are pushed to a Docker registry.
 
+``repo2docker`` is the tool used by `BinderHub <https://binderhub.readthedocs.io>`_
+to build images on demand.
+
 Please report `Bugs <https://github.com/jupyter/repo2docker/issues>`_,
 `ask questions <https://gitter.im/jupyterhub/binder>`_ or
 `contribute to the project <https://github.com/jupyter/repo2docker/blob/master/CONTRIBUTING.md>`_.
@@ -25,16 +28,11 @@ Please report `Bugs <https://github.com/jupyter/repo2docker/issues>`_,
 
 .. toctree::
    :maxdepth: 2
-   :caption: How-To: User interfaces and environments
+   :caption: How-To guides
 
    howto/user_interface
    howto/languages
    howto/lab_workspaces
-
-.. toctree::
-   :maxdepth: 2
-   :caption: How-To: Deployment and administration
-
    howto/jupyterhub_images
    howto/deploy
 

docs/source/usage.rst

@@ -55,7 +55,7 @@ Pasting the URL into your browser will open Jupyter Notebook with the
 dependencies and contents of the source repository in the built image.
 
 
-Building a specific branch / commit / tag
+Building a specific branch, commit or tag
 =========================================
 
 To build a particular branch and commit, use the argument ``--ref`` and
@@ -64,7 +64,7 @@ specify the ``branch-name`` or ``commit-hash``. For example::
   jupyter-repo2docker --ref 9ced85dd9a84859d0767369e58f33912a214a3cf https://github.com/norvig/pytudes
 
 .. tip::
-   For reproducible research, we recommend specifying a commit-hash to
+   For reproducible builds, we recommend specifying a commit-hash to
    deterministically build a fixed version of a repository. Not specifying a
    commit-hash will result in the latest commit of the repository being built.
 
@@ -78,7 +78,10 @@ Where to put configuration files
 * The root directory of the repository.
 
 If the folder ``binder/`` is located at the top level of the repository,
-  **only configuration files in the** ``binder/`` **folder will be considered**.
+only configuration files in the ``binder/`` folder will be considered.
+
+Check the complete list of :ref:`configuration files <config-files>` supported
+by ``repo2docker`` to see how to configure the build process.
 
 .. note::