From a5ab75003819826257a76e0f7178b1ed0aa65a4d Mon Sep 17 00:00:00 2001 From: Chris Holdgraf Date: Fri, 8 Dec 2017 11:53:15 -0800 Subject: [PATCH] addressing carol's comments --- README.md | 6 +++-- docs/source/faq.md | 2 +- docs/source/install.rst | 17 +++++++------ docs/source/usage.rst | 56 ++++++++++++++++++++++------------------- 4 files changed, 45 insertions(+), 36 deletions(-) diff --git a/README.md b/README.md index 36f55cd0..9a6a900a 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,8 @@ [![Build Status](https://travis-ci.org/jupyter/repo2docker.svg?branch=master)](https://travis-ci.org/jupyter/repo2docker) [![Documentation Status](https://readthedocs.org/projects/repo2docker/badge/?version=latest)](http://repo2docker.readthedocs.io/en/latest/?badge=latest) -**jupyter-repo2docker** is a tool to build, run and push Docker images from source code repositories. +**jupyter-repo2docker** takes as input a repository source, such as a GitHub repo. It then builds, runs, and/or pushes Docker images built from +that source. See the [repo2docker documentation](http://repo2docker.readthedocs.io) for more information. @@ -62,7 +63,8 @@ For more information on how to use ``repo2docker``, see the ## Repository specifications -Repo2Docker looks for configuration files in the repository being built to figure out how to build it. +Repo2Docker looks for configuration files in the source repository to +determine how the Docker image should be built. It is philosophically similar to [Heroku Build Packs](https://devcenter.heroku.com/articles/buildpacks). For a list of the configuration files that ``repo2docker`` can use, diff --git a/docs/source/faq.md b/docs/source/faq.md index cc0ea916..f2ad67e9 100644 --- a/docs/source/faq.md +++ b/docs/source/faq.md @@ -6,7 +6,7 @@ If you have a question & 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 an ``environment.yaml`` +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. ## Can I use repo2docker to bootstrap my own Dockerfile? diff --git a/docs/source/install.rst b/docs/source/install.rst index c4b58991..a01acc15 100644 --- a/docs/source/install.rst +++ b/docs/source/install.rst @@ -3,16 +3,19 @@ Installing ``repo2docker`` ========================== -Installing ``repo2docker`` is easiest using the python -packaging index. In addition, you need to install -`Docker `_ as it is required in -order to build images. +1. Install `Docker `_ as it is required to build Docker images. -To install ``repo2docker`` from pypi, the python packaging index:: +2. We recommend installing ``repo2docker`` with the ``pip`` tool:: - pip install jupyter-repo2docker + python3 -m pip install jupyter-repo2docker -To install from source and start contributing:: +For infomation on using ``repo2docker``, see :ref:`usage`. + +Installing repo2docker from source code +--------------------------------------- + +Alternatively, you can install repo2docker from source, +i.e. if you are contributing back to this project:: git clone https://github.com/jupyter/repo2docker.git cd repo2docker diff --git a/docs/source/usage.rst b/docs/source/usage.rst index 708eccac..55fee203 100644 --- a/docs/source/usage.rst +++ b/docs/source/usage.rst @@ -3,16 +3,20 @@ Using ``repo2docker`` ===================== -The core feature of repo2docker is to fetch a repo (from github or locally), -build a container image based on the specifications found in the -repo & optionally launch a local Jupyter Notebook you can use to explore it. +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. This section describes the general ways in which you can use -``repo2docker``. It covers basics in how to prepare your -repository for building, as well as how to use ``repo2docker`` -to build repositories on your own. +``repo2docker``, including: -See the `Frequently Asked Questions `_ for more info. +.. contents:: + :depth: 1 + :local: + +.. note:: + + See the `Frequently Asked Questions `_ for more info. Preparing your repository ------------------------- @@ -22,9 +26,9 @@ to determine how to build it. It is philosophically similar to `Heroku Build Packs `_. ``repo2docker`` will look for files in two places: -* The root of the repository. -* A folder called ``binder`` in the root of the repository (if this folder - exists, configuration files in the root of the repository will be ignored). +* A folder called ``binder`` in the root of the repository. +* The root of the repository. (if a folder called ``binder`` exists in the root + of the repository, configuration files outside of that folder will be ignored) .. note:: @@ -33,19 +37,20 @@ to determine how to build it. It is philosophically similar to creating new custom configuration files. ``repodocker`` configuration files are all composable - you can use any number -of them in the same repository, with a few notable exceptions: +of them in the same repository. There are a few notable rules: * ``Dockerfile``: if a Dockerfile is present in a repository, it will take precedence over all other configuration files (which will be ignored). -* ``environment.yaml`` with ``requirements.txt``: If both of these files are - present, then ``environment.yaml`` will be used to build the image, **not** +* ``environment.yml`` with ``requirements.txt``: If both of these files are + present, then ``environment.yml`` will be used to build the image, **not** ``requirements.txt``. If you wish to ``pip install`` packages using an - ``environment.yaml`` file, `you should do so with the + ``environment.yml`` file, `you should do so with the *pip:* key `_. .. note:: - For a list of sample repositories, see :ref:`samples`. + For a list of repositories demonstrating various configurations, + see :ref:`samples`. Supported configuration files ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -62,9 +67,10 @@ This specifies a list of python packages that would be installed in a virtualenv This is a conda environment specification, that lets you install packages with conda. -.. note:: +.. important:: - You must leave the name of the environment empty for this to work out of the box. + You must leave the ``environment.yml``'s name field empty for this + to work out of the box. ``apt.txt`` ^^^^^^^^^^^ @@ -88,13 +94,12 @@ want this to be a shell script, make sure the first line is `#!/bin/bash`. ``REQUIRE`` ^^^^^^^^^^^ -This specifies a list of Julia packages! Currently only version 0.6 of Julia is supported, but more will -be as they are released. +This specifies a list of Julia packages! .. note:: Using a ``REQUIRE`` file also requires that the repository contain an - ``environment.yaml`` file. + ``environment.yml`` file. ``Dockerfile`` ^^^^^^^^^^^^^^ @@ -109,7 +114,7 @@ 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.yaml``:: +you should put the following in ``requirements.txt`` or ``environment.yml``:: jupyterhub==0.8.* @@ -133,14 +138,13 @@ You can do this with the following command:: jupyter-repo2docker https://github.com/jakevdp/PythonDataScienceHandbook -After building (it might take a while!), it should output in your terminal -something like:: +After building (it might take a while!), it should output a message in your terminal:: 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 -If you copy paste that URL into your browser you will see a Jupyter Notebook with the +If you copy/paste that URL into your browser you will see a Jupyter Notebook with the contents of the repository you have just built! Displaying the image Dockerfile @@ -155,8 +159,8 @@ the ``--debug`` and ``--no-build`` flags like so:: This will output the contents of the Dockerfile in your console. Note that it will **not** build the image. -Other build configurations --------------------------- +Accessing help from the command line +------------------------------------ For a list of all the build configurations at your disposal, see the CLI help::