Update documentation with more cross references
MODIFY
docs/source/config_files.rst
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
=========================================

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

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

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

Update documentation with more cross references