updating per Tim comments and adding howto section
MODIFY
docs/source/config_files.rst
docs/source/config_files.rst
@@ -67,10 +67,6 @@ 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 .``.
-While one can specify dependencies in ``setup.py``,
-repo2docker **requires configuration files such as** ``environment.yml`` or
-``requirements.txt`` to install dependencies during the build process.
-
``REQUIRE`` - Install a Julia environment
=========================================
@@ -141,7 +137,7 @@ If you only need to run things once during the build phase use :ref:`postBuild`.
This allows you to control the runtime of Python or R.
-To use python-2.7: add python-2.7 in runtime.txt file.
+To use python-2.7: add ``python-2.7`` in runtime.txt file.
The repository will run in a virtualenv with
Python 2 installed. To see a full example repository, visit our
`Python2 example <https://github.com/binder-examples/python2_runtime/blob/master/runtime.txt>`_.
@@ -168,5 +164,5 @@ trying the other configuration files before deciding to use your own Dockerfile.
With Dockerfiles, a regular Docker build will be performed.
**If a Dockerfile is present, all other configuration files will be ignored.**
-See the `Binder Documentation <https://mybinder.readthedocs.io/en/latest/dockerfile.html>`_ for
+See the `Advanced Binder Documentation <https://mybinder.readthedocs.io/en/latest/dockerfile.html>`_ for
best-practices with Dockerfiles.

ADD
docs/source/howto/jupyterhub_images.rst
+.. _jupyterhub_images:
+
+=============================
+Build JupyterHub-ready images
+=============================
+
+JupyterHub_ allows multiple
+users to collaborate on a shared Jupyter server. ``repo2docker`` can build
+Docker images that can be shared within a JupyterHub deployment. For example,
+`mybinder.org <https://mybinder.org>`_ uses JupyterHub and ``repo2docker``
+to allow anyone to build a Docker image of a git repository online and
+share an executable version of the repository with a URL to the built image.
+
+To build JupyterHub_-ready Docker images with ``repo2docker``, the
+version of your JupterHub deployment must be included in the
+``environment.yml`` or ``requirements.txt`` of the git repositories you
+build.
+
+If your instance of JupyterHub uses ``DockerSpawner``, you will need to set its
+command to run ``jupyterhub-singleuser`` by adding this line in your
+configuration file::
+
+ c.DockerSpawner.cmd = ['jupyterhub-singleuser']
+
+.. _JupyterHub: https://github.com/jupyterhub/jupyterhub

ADD
docs/source/howto/languages.rst
+.. _languages:
+
+=====================================
+Choose languages for your environment
+=====================================
+
+You can define many different languages in your configuration files. This
+page describes how to use some of the more common ones.
+
+Python
+======
+
+Your environment will have Python (and specified dependencies) installed when
+you use one of the following configuration files:
+
+* ``requirements.txt``
+* ``environment.yml``
+
+Note that by default, the environment will have **Python 3** installed.
+
+Specifying a version of Python
+------------------------------
+
+To specify a specific version of Python, you have two options:
+
+* **use ``runtime.txt``**. Include a line that specifies the Python version in
+ this file. This line takes the following form::
+
+ python=X.X
+
+ For example,::
+
+ python=2.7
+* **Use ``environment.yml``**. The Anaconda distribution also lets you define
+ the Python environment within ``environment.yml``. To do so, add ``python=X.X``
+ to your dependencies section, like so::
+
+ name: python 2.7
+ dependencies:
+ - python=2.7
+ - numpy
+
+The R Language
+==============
+
+To ensure that R is installed, you must specify a version of R in a ``runtime.txt``
+file. This takes the following form::
+
+ r-YYYY-MM-DD
+
+The date corresponds to the state of the MRAN repository at this day. Make sure
+that you choose a day with the desired version of your packages. For example,
+to use the MRAN repository on January 1st, 2018, add this line to ``runtime.txt``::
+
+ r-2018-01-01
+
+Note that to install specific packages with the R environment, you should
+use the ``install.R`` configuration file.
+
+Julia
+=====
+
+To build an environment with Julia, include a configuration file called
+``REQUIRE``. Each line of this file should include a package that you wish
+to have installed with Julia. For example, the following contents of ``REQURE``
+would install the ``PyPlot`` package with your Julia environment.::
+
+ PyPlot
+
+Languages not covered here
+==========================
+
+If a language is not "officially" supported by a build pack, it can often be
+installed with a ``postBuild`` script. This will run arbitrary ``bash`` commands,
+and can be used to download / install a language.
+
+Using multiple languages at once
+================================
+
+It may also be possible to combine multiple languages in a single environment.
+The details on how to accomplish this with all possible combinations are outside
+the scope of this guide. However we recommend that you take a look at the
+`Multi-Language Demo <https://github.com/binder-examples/multi-language-demo>`_
+repository for some inspiration.

ADD
docs/source/howto/user_interface.rst
+.. _user_interface:
+
+============================
+Configure the user interface
+============================
+
+You can build several user interfaces into the resulting Docker image.
+This is controlled with various :ref:`configuration files <config-files>`.
+
+JupyterLab
+----------
+
+You do not need any extra configuration in order to allow the use
+of the JupyterLab interface. You can launch JupyterLab from within a user
+session by opening the Jupyter Notebook and appending ``/lab`` to the end of the URL
+like so:
+
+.. code-block:: none
+
+ http(s)://<server:port>/lab
+
+To switch back to the classic notebook, add ``/tree`` to the URL like so:
+
+.. code-block:: none
+
+ http(s)://<server:port>/tree
+
+To learn more about URLs in JupyterLab and Jupyter Notebook, visit
+`starting JupyterLab <http://jupyterlab.readthedocs.io/en/latest/getting_started/starting.html>`_.
+
+RStudio
+-------
+
+The RStudio user interface is automatically enabled a configuration file for
+R is detected (an R version specified in ``runtime.txt``). If this is detected,
+RStudio will be accessible by appending ``/rstudio`` to the URL, like so:
+
+.. code-block:: none
+
+ http(s)://<server:port>/rstudio

MODIFY
docs/source/index.rst
docs/source/index.rst
@@ -22,9 +22,17 @@ Please report `Bugs <https://github.com/jupyter/repo2docker/issues>`_,
install
usage
+.. toctree::
+ :maxdepth: 1
+ :caption: How-to...
+
+ howto/user_interface
+ howto/languages
+ howto/jupyterhub_images
+
.. toctree::
:maxdepth: 2
- :caption: Configuration files and examples
+ :caption: Complete list of configuration files
config_files

MODIFY
docs/source/usage.rst
docs/source/usage.rst
@@ -87,47 +87,6 @@ If the folder ``binder/`` is located at the top level of the repository,
:ref:`configuration files <config-files>`.
-.. _user_interface:
-
-Specifying the user interface
-=============================
-
-repo2docker can build several user interfaces into the resulting Docker image.
-This is controlled with various :ref:`configuration files <config-files>`.
-
-JupyterLab
-----------
-
-repo2docker does not need any extra configuration in order to allow the use
-of the JupyterLab interface. You can launch JupyterLab from within a repo2docker
-image by opening the Jupyter Notebook and appending ``/lab`` to the end of the URL
-like so:
-
-.. code-block:: none
-
- http(s)://<server:port>/lab
-
-To switch back to the classic notebook, add ``/tree`` to the URL like so:
-
-.. code-block:: none
-
- http(s)://<server:port>/tree
-
-To learn more about URLs in JupyterLab and Jupyter Notebook, visit
-`starting JupyterLab <http://jupyterlab.readthedocs.io/en/latest/getting_started/starting.html>`_.
-
-RStudio
--------
-
-The RStudio user interface is enabled when repo2docker detects a configuration
-for R (an R version specified in ``runtime.txt``). If this is detected,
-RStudio will be accessible by appending ``/rstudio`` to the URL, like so:
-
-.. code-block:: none
-
- http(s)://<server:port>/rstudio
-
-
Debugging repo2docker with ``--debug`` and ``--no-build``
=========================================================
@@ -148,27 +107,4 @@ be used by docker directly.
jupyter-repo2docker --no-build --debug https://github.com/norvig/pytudes
-
-Building JupyterHub-ready images
-================================
-
-JupyterHub_ allows multiple
-users to collaborate on a shared Jupyter server. ``repo2docker`` can build
-Docker images that can be shared within a JupyterHub deployment. For example,
-`mybinder.org <https://mybinder.org>`_ uses JupyterHub and ``repo2docker``
-to allow anyone to build a Docker image of a git repository online and
-share an executable version of the repository with a URL to the built image.
-
-To build JupyterHub_-ready Docker images with ``repo2docker``, the
-version of your JupterHub deployment must be included in the
-``environment.yml`` or ``requirements.txt`` of the git repositories you
-build.
-
-If your instance of JupyterHub uses ``DockerSpawner``, you will need to set its
-command to run ``jupyterhub-singleuser`` by adding this line in your
-configuration file::
-
- c.DockerSpawner.cmd = ['jupyterhub-singleuser']
-
-.. _JupyterHub: https://github.com/jupyterhub/jupyterhub
.. _Pytudes: https://github.com/norvig/pytudes

updating per Tim comments and adding howto section