reorganized to close and closes
MODIFY
docs/source/config_files.rst
docs/source/config_files.rst
.. _config-files:
-Supported configuration files
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Configuration Files
+~~~~~~~~~~~~~~~~~~~
-Below is a list of supported configuration files (roughly in the order of build priority).
+``repo2docker`` looks for configuration files in the repository being built
+to determine how to build it. It is philosophically similar to
+`Heroku Build Packs <https://devcenter.heroku.com/articles/buildpacks>`_.
+
+In general, ``repo2docker`` uses the same configuration files as other software
+installation tools, rather than creating new custom configuration files.
+These files are described in :ref:`config-files`.
+
+``repo2docker`` configuration files are **composable**- you can use any number
+of them in the same repository.
+
+``repo2docker`` will look for configuration files in either:
+
+* A folder named ``binder`` in the root of the repository.
+* The root 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**.
+
+`binder examples <https://github.com/binder-examples>`_ contains a list of
+example repositories that can be built with ``repo2docker`` with various
+configuration files.
+
+Below is a list of supported configuration files (roughly in the order of build priority):
.. contents::
:local:
@@ -22,6 +45,8 @@ With Dockerfiles, a regular Docker build will be performed.
See the `Binder Documentation <https://mybinder.readthedocs.io/en/latest/dockerfile.html>`_ for
best-practices with Dockerfiles.
+.. _environment-yml:
+
``environment.yml``
^^^^^^^^^^^^^^^^^^^
@@ -75,6 +100,8 @@ 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.
+.. _postBuild:
+
``postBuild``
^^^^^^^^^^^^^

MODIFY
docs/source/faq.md
docs/source/faq.md
# Frequently Asked Questions (FAQ)
-A collection of frequently asked questions with answers!
-
-If you have a question & have found an answer, send a PR to add it here!
+A collection of frequently asked questions with answers. If you have a question
+and have found an answer, send a PR to add it here!
## How should I specify another version of Python 3?
-Currently the best way to do this is by using a conda ``environment.yml``
-file and setting the language to whichever version of Python you like.
+One can specify a Python version in the ``environment.yml`` file of a repo.
## Can I add executable files to the user's PATH?
-Yes! Using a ``postBuild`` file, you can place any files that should be called
+Yes! With a :ref:`postBuild` file, you can place any files that should be called
from the command line in the folder ``~/.local/``. This folder will be
available in a user's PATH, and can be run from the command line (or as
a subsequent build step.)
@@ -36,4 +34,4 @@ Hence the output of `--debug` can not be built with a normal `docker build -t .`
or similar traditional docker command.
Check out the [binder-examples](http://github.com/binder-examples/) github
-organization for example Dockerfiles you can copy & modify for your own use!
+organization for example repositories you can copy & modify for your own use!

MODIFY
docs/source/index.rst
docs/source/index.rst
@@ -2,8 +2,11 @@ jupyter-repo2docker
===================
**jupyter-repo2docker** is a tool to build, run, and push Docker
-images from source code repositories. See the list below for various
-ways in which you can use ``repo2docker``.
+images from source code repositories. repo2docker fetches a repo
+(e.g., from GitHub or other locations) and builds a container image based
+on the specifications found in the repo.
+Optionally, it can launch a local
+Jupyter Notebook which you can use to explore it.
Please report `Bugs <https://github.com/jupyter/repo2docker/issues>`_,
`ask questions <https://gitter.im/jupyterhub/binder>`_ or

MODIFY
docs/source/install.rst
docs/source/install.rst
Installing ``repo2docker``
==========================
+repo2docker requires Python 3.4 and above on Linux and macOS. See
+:ref:`below <windows>` for more information about Windows support.
+
Prerequisite: docker
--------------------
-Install `Docker <https://www.docker.com>`_ as it is required to build Docker images.
+Install `Docker <https://www.docker.com>`_ as it is required
+to build Docker images. The
+`Community Edition <https://www.docker.com/community-edition>`_,
+is available for free.
+
+Recent versions of Docker are recommended.
+The latest version of Docker, ``18.03``, successfully builds repositories from
+`binder-examples <https://github.com/binder-examples>`_.
+The `BinderHub <https://binderhub.readthedocs.io/>`_ helm chart uses version
+``17.11.0-ce-dind``. See the
+`helm chart <https://github.com/jupyterhub/binderhub/blob/master/helm-chart/binderhub/values.yaml#L167>`_
+for more details.
Installing with ``pip``
-----------------------
@@ -30,8 +44,10 @@ i.e. if you are contributing back to this project::
That's it! For information on using ``repo2docker``, see
:ref:`usage`.
-Note about Windows support
---------------------------
+.. _windows:
+
+Windows support
+---------------
Windows support by ``repo2docker`` is still in the experimental stage.
@@ -40,3 +56,11 @@ Bash on Windows) provides additional information about Windows and docker.
.. _using Windows and the WSL: https://nickjanetakis.com/blog/setting-up-docker-for-windows-and-wsl-to-work-flawlessly
+
+JupyterHub-ready images
+-----------------------
+
+To build `JupyterHub <https://github.com/jupyterhub/jupyterhub>`_-ready
+Docker images with ``repo2docker``, the version of your JupterHub deployment
+must be included in the ``environment.yml`` or ``requiements.txt`` of the
+git repositories you build.

MODIFY
docs/source/usage.rst
docs/source/usage.rst
Using ``repo2docker``
=====================
-The core functionality of repo2docker is to fetch a repo (e.g., from GitHub or
-other locations) and build a container image based on the specifications found in the
-repo. Optionally, it can launch a local Jupyter Notebook which you can use to explore it.
+`Docker <https://docs.docker.com/>`_ **must be running ** in
+order to run ``repo2docker``. For more information on installing
+``repo2docker``, see :ref:`install`.
-This section describes the general ways in which you can use
-``repo2docker``, including:
+``repo2docker`` performs two steps:
-.. contents::
- :depth: 1
- :local:
-
-
-See the `Frequently Asked Questions <faq.html>`_ for additional information.
-
-Preparing your repository
--------------------------
-
-``repo2docker`` looks for configuration files in the repository being built
-to determine how to build it. It is philosophically similar to
-`Heroku Build Packs <https://devcenter.heroku.com/articles/buildpacks>`_.
-
-In general, ``repo2docker`` uses the same configuration files as other software
-installation tools, rather than creating new custom configuration files.
-These files are described in :ref:`config-files`.
-
-``repo2docker`` configuration files are all **composable** - you can use any number
-of them in the same repository.
-
-Locating and composing configuration files
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-``repo2docker`` will look for configuration files located in two places:
+1. builds a Docker image from a git repo
+2. runs a Jupyter server within the image to explore the repo
-* A folder named ``binder`` in the root of the repository.
-* The root of the repository.
+To ensure you can run the software in your repository, you must
-There are a few notable rules for composition precedence and build priority:
+repo2docker is called with a simple command::
-* If the folder ``binder`` is located at the top level of the repository,
- **only configuration files in the** ``binder`` **folder will be considered**.
-* If a Dockerfile is present, **all other files will be ignored**.
-* ``environment.yml`` **takes precedent over**
- ``requirements.txt``. If you wish to install ``pip`` packages
- with ``environment.yml``, please use the
- ``pip:`` key as described in the `conda documentation`_.
+ jupyter-repo2docker <URL-or-path to repo>
-For a list of repositories demonstrating various configurations, see
-`binder examples <https://github.com/binder-examples>`_.
+where ``<URL-or-path to repo>`` is a URL or path to the source repository.
-Preparing a repo to build JupyterHub-ready images
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+For example, use the following to build an image of the
+`Python Data Scinece Handbook <https://github.com/jakevdp/PythonDataScienceHandbook>`_::
-It is possible to use ``repo2docker`` to build JupyterHub-ready
-Docker images. 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``::
+ jupyter-repo2docker https://github.com/jakevdp/PythonDataScienceHandbook
- jupyterhub==0.8.*
+To build a particular branch and commit, we use the argument ``--ref`` to
+specify the ``branch-name/commit-hash``::
-Running ``repo2docker`` locally
--------------------------------
+ jupyter-repo2docker https://github.com/jakevdp/PythonDataScienceHandbook --ref master/599aa0fe3f882c0001670e676e5a8d43b92c35fc
-`Docker <https://docs.docker.com/>`_ **must be running on your machine** in order to build images
- with ``repo2docker``.
- For more information on installing ``repo2docker``, see :ref:`install`.
+Building the image may take a few minutes.
+During building, ``repo2docker``
+clones the repository to obtain its contents and inspects the repo for
+:ref:`configuration files <config-files>`.
+`Python Data Scinece Handbook <https://github.com/jakevdp/PythonDataScienceHandbook>`_
+uses a `requirements.txt file <https://github.com/jakevdp/PythonDataScienceHandbook/blob/master/requirements.txt>`_
+to specify its Python environment. ``repo2docker`` uses ``pip`` to install
+dependencies listed in the ``requirement.txt`` in image. To learn more about
+configuration files in ``repo2docker`` visit :ref:`config-files`.
-The simplest invocation of ``repo2docker`` performs two steps:
+When the image is built, a message will be output to your terminal::
-1. builds a Docker image from a git repo
-2. runs a Jupyter server within the image
-
-This two step process enables you to build an image and run it so you can
-explore the repository's contents.
+ Copy/paste this URL into your browser when you connect for the first time,
+ to login with a token:
+ http://0.0.0.0:36511/?token=f94f8fabb92e22f5bfab116c382b4707fc2cade56ad1ace0
-The **command** used is::
+Pasting the URL into your browser will open Jupyter Notebook with the
+dependencies and contents of the source repository in the built image.
- jupyter-repo2docker <URL-or-path to repo>
+Because JupyterLab is a server extension of the classic Jupyter Notebook server,
+you can launch JupyterLab by opening Jupyter Notebook and visiting the
+```/lab`` to the end of the URL:
-where ``<URL-or-path to repo>`` provides a URL or path to the source repository.
+.. code-block:: none
-For example, use the following to build an image and launch a Jupyter Notebook
-server::
+http(s)://<server:port>/<lab-location>/lab
- jupyter-repo2docker https://github.com/jakevdp/PythonDataScienceHandbook
+To switch back to the classic notebook, add ``/tree`` to the URL:
-When the example completes building (which may take a few minutes), a message will
-be output to your terminal::
+.. code-block:: none
- Copy/paste this URL into your browser when you connect for the first time,
- to login with a token:
- http://0.0.0.0:36511/?token=f94f8fabb92e22f5bfab116c382b4707fc2cade56ad1ace0
+http(s)://<server:port>/<lab-location>/tree
-If you copy/paste that URL into your browser you will see a Jupyter Notebook with the
-contents of the source repository which you have just built.
+To learn more about URLs in JupyterLab and Jupyter Notebook, visit
+`starting JupyterLab <http://jupyterlab.readthedocs.io/en/latest/getting_started/starting.html>`_.
-Using the ``--debug`` and ``--no-build`` parameters
----------------------------------------------------
+``--debug`` and ``--no-build``
+------------------------------
-If you want to debug and understand the details of the docker image being built,
-you can pass the ``debug`` parameter to the commandline:
+To debug the docker image being built, pass the ``--debug`` parameter:
.. code-block:: bash
@@ -120,22 +86,3 @@ be used by docker directly.
.. code-block:: bash
jupyter-repo2docker --no-build --debug https://github.com/jakevdp/PythonDataScienceHandbook
-
-Setting environment variables
------------------------------
-
-If you want to define environment variables, you can pass the ``--env`` or ``-e`` parameter to the commandline:
-
- .. code-block:: bash
-
- jupyter-repo2docker -e VAR1=val1 -e VAR2=val2 ...
-
-Accessing help from the command line
-------------------------------------
-
-For a list of all the build configurations at your disposal, see the
-CLI help::
-
- jupyter-repo2docker -h
-
-.. _conda documentation: https://conda.io/docs/user-guide/tasks/manage-environments.html#creating-an-environment-file-manually

reorganized to close #332 and closes #333