diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6f375fb41..25849e945 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -33,7 +33,7 @@ make that your current directory with `cd repo2docker`. ### Set up a local virtual environment -After cloning the repository (or your fork of the repo), you should set up an +After cloning the repository (or your fork of the repository), you should set up an isolated environment to install libraries required for running / developing repo2docker. There are many ways to do this, and a `virtual environment` is one of them. @@ -102,7 +102,7 @@ py.test -s tests/ ## Update and Freeze BuildPack Dependencies -### Updating libraries installed for all repos +### Updating libraries installed for all repositories For both the `conda` and `virtualenv` (`pip`) base environments in the **Conda BuildPack** and **Python BuildPack**, we install specific pinned versions of all dependencies. We explicitly list the dependencies @@ -210,7 +210,7 @@ individuals to be responsible and tread softly when doing so. Below a few standard procedures that have proven useful over time that we do follow: * do not merge your own PR -* wait for travis to complete +* wait for Travis to complete * check if test coverage has gone up or down, consider discussing additional tests to keep coverage at the same level or even increase it * do use merge commits instead of merge-by-squashing/-rebasing. This makes it @@ -229,7 +229,7 @@ To release repo2docker, you will need proper access credentials prior to beginni 1. Access to the PyPI package for repo2docker 2. Access to push tags to the jupyter/repo2docker repository -3. Acess to push images to dockerhub on jupyter/repo2docker +3. Access to push images to dockerhub on jupyter/repo2docker If you do not have access to any of these, please contact a current maintainer of the project! diff --git a/README.md b/README.md index 88b44174e..088665aee 100644 --- a/README.md +++ b/README.md @@ -4,12 +4,12 @@ [![Documentation Status](https://readthedocs.org/projects/repo2docker/badge/?version=latest)](http://repo2docker.readthedocs.io/en/latest/?badge=latest) **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. +repository. It then builds, runs, and/or pushes Docker images built from that source. See the [repo2docker documentation](http://repo2docker.readthedocs.io) for more information. -## Pre-requisites +## Prerequisites 1. Docker to build & run the repositories. The [community edition](https://store.docker.com/search?type=edition&offering=community) is recommended. @@ -35,8 +35,8 @@ pip install -e . ## Usage -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 & +The core feature of repo2docker is to fetch a repository (from GitHub or locally), +build a container image based on the specifications found in the repository & optionally launch a local Jupyter Notebook you can use to explore it. **Note that Docker needs to be running on your machine for this to work.** diff --git a/docs/source/architecture.md b/docs/source/architecture.md index be5329165..93437f17c 100644 --- a/docs/source/architecture.md +++ b/docs/source/architecture.md @@ -7,7 +7,7 @@ from various perspectives. The **buildpack** concept comes from [Heroku](https://devcenter.heroku.com/articles/buildpacks) and Ruby on Rails' [Convention over Configuration](http://rubyonrails.org/doctrine/#convention-over-configuration) -doctrine. +doctrine. Instead of the user specifying a complete specification of exactly how they want their environment to be, they can focus only on how their environment differs from a conventional @@ -31,7 +31,7 @@ It takes the following steps to determine this: 1. Look at the ordered list of `BuildPack` objects listed in `Repo2Docker.buildpacks` traitlet. This is populated with a default set of buildpacks in most-specific-to-least-specific - order. Other applications using this can add / change this using traditional + order. Other applications using this can add / change this using traditional [traitlet](http://traitlets.readthedocs.io/en/stable/) configuration mechanisms. 2. Calls the `detect` method of each `BuildPack` object. This method assumes that the repository is present in the current working directory, and should return `True` if the repository is @@ -39,24 +39,24 @@ It takes the following steps to determine this: libraries can check for presence of an `environment.yml` file and say 'yes, I can handle this repository' by returning `True`. Usually buildpacks look for presence of specific files (`requirements.txt`, `environment.yml`, `install.R`, etc) to determine if they can handle a - repository or not. + repository or not. 3. If no `BuildPack` returns true, then repo2docker will use the default `BuildPack` (defined in `Repo2Docker.default_buildpack` traitlet). ## Build base environment Once a buildpack is chosen, it builds a **base environment** that is mostly the same for various -repositories built with the same buildpack. +repositories built with the same buildpack. For example, in `CondaBuildPack`, the base environment consists of installing [miniconda](https://conda.io/miniconda.html) and basic notebook packages (from `repo2docker/buildpacks/conda/environment.yml`). This is going -to be the same for most repositories built with `CondaBuildPack`, so we want to use -[docker layer caching](https://thenewstack.io/understanding-the-docker-cache-for-faster-builds/) as +to be the same for most repositories built with `CondaBuildPack`, so we want to use +[docker layer caching](https://thenewstack.io/understanding-the-docker-cache-for-faster-builds/) as much as possible for performance reasons. Next time a repository is built with `CondaBuildPack`, we can skip straight to the **copy** step (since the base environment docker image *layers* have already been built and cached). -The `get_build_scripts` and `get_build_script_files` methods are primarily used for this. +The `get_build_scripts` and `get_build_script_files` methods are primarily used for this. `get_build_scripts` can return arbitrary bash script lines that can be run as different users, and `get_build_script_files` is used to copy specific scripts (such as a conda installer) into the image to be run as pat of `get_build_scripts`. Code in either has following constraints: @@ -82,10 +82,10 @@ the `build` method of the `BuildPack` base class. The **assemble** stage builds the specific environment that is requested by the repository. This usually means installing required libraries specified in a format native to the language -(`requirements.txt`, `environment.yml`, `REQUIRE`, `install.R`, etc). +(`requirements.txt`, `environment.yml`, `REQUIRE`, `install.R`, etc). Most of this work is done in `get_assemble_scripts` method. It can return arbitrary bash script -lines that can be run as different users, and has access to the repository contents (unlike +lines that can be run as different users, and has access to the repository contents (unlike `get_build_scripts`). The docker image layers produced by this usually can not be cached, so less restrictions apply to this than to `get_build_scripts`. diff --git a/docs/source/config_files.rst b/docs/source/config_files.rst index 7d93be9b3..b13a39327 100644 --- a/docs/source/config_files.rst +++ b/docs/source/config_files.rst @@ -24,7 +24,7 @@ If the folder ``binder/`` is located at the top level of the repository, The `binder examples `_ organization on GitHub contains a list of sample repositories for common configurations that ``repo2docker`` can build with various configuration files such as -Python and R installation in a repo. +Python and R installation in a repository. Below is a list of supported configuration files (roughly in the order of build priority): diff --git a/docs/source/deploy.rst b/docs/source/deploy.rst index bafb82ca2..ee442bd60 100644 --- a/docs/source/deploy.rst +++ b/docs/source/deploy.rst @@ -79,7 +79,7 @@ Step 4. Connect to CircleCI If you navigate to the main `app page `_ you should be able to click "Add Projects" and then select your repository. If you don't see it on the list, then select a different organization in the top left. Once -you find the repository, you can click the button to "Start Building" adn accept +you find the repository, you can click the button to "Start Building" and accept the defaults. Before you push or trigger a build, let's set up the following environment variables. @@ -103,7 +103,7 @@ Step 5. Push Away, Merrill! Once the environment variables are set up, you can push or issue a pull request to see circle build the workflow. Remember that you only need the ``.circleci/config.yml`` -and not any other files in the repository. If your notebook is hosted in the same repo, +and not any other files in the repository. If your notebook is hosted in the same repository, you might want to add these, along with your requirements.txt, etc. .. tip:: diff --git a/docs/source/design.md b/docs/source/design.md index 6054a64ac..8826ecd2c 100644 --- a/docs/source/design.md +++ b/docs/source/design.md @@ -7,7 +7,7 @@ The philosophy for the repo2docker buildpacks includes: - using common configuration files for familiar installation and packaging tools - allowing configuration files to be combined to compose more complex setups - specifying default locations for configuration files -(repo's root directory or .binder directory) +(the repository's root directory or .binder directory) When designing `repo2docker` and adding to it in the future, the @@ -57,7 +57,7 @@ Bionic Beaver (18.04). The version of `repo2docker` used to build an image can influence which packages are installed by default and which features are supported during the build process. We will periodically update those packages to keep step with releases -of jupyter notebook, jupyterlab, etc. For packages that are installed by +of Jupyter Notebook, JupyterLab, etc. For packages that are installed by default but where you want to control the version we recommend you specify them explicitly in your dependencies. diff --git a/docs/source/dev_newbuildpack.md b/docs/source/dev_newbuildpack.md index fd6dd7c64..1de331a76 100644 --- a/docs/source/dev_newbuildpack.md +++ b/docs/source/dev_newbuildpack.md @@ -12,15 +12,15 @@ Criteria to balance are: 2. How easy it is to use a given setup without support from repo2docker natively. There are two escape hatches here - `postBuild` and `Dockerfile`. 3. How widely used is this language / package manager? This is the primary tradeoff - with point (1). We (Binder / Jupyter) team do not want to make new formats - as much as possible, so ideally we can just say 'X repos on binder already use + with point (1). We (the Binder / Jupyter team) want to make new formats + as little as possible, so ideally we can just say "X repositories on binder already use this using one of the escape hatches in (2), so let us make it easy and add - native support'. + native support". ## Adding libraries or UI to existing buildpacks Note that this doesn't apply to adding additional libraries / UI to existing buildpacks. For example, if we had an R buildpack and it supported IRKernel, it is much easier to -just support RStudio / Shiny with it, since those are library additions than entirely +just support RStudio / Shiny with it, since those are library additions instead of entirely new buildpacks. diff --git a/docs/source/faq.md b/docs/source/faq.md index dd5559280..b896a79f6 100644 --- a/docs/source/faq.md +++ b/docs/source/faq.md @@ -5,7 +5,7 @@ and have found an answer, send a PR to add it here! ## How should I specify another version of Python 3? -One can specify a Python version in the ``environment.yml`` file of a repo. +One can specify a Python version in the ``environment.yml`` file of a repository. ## Can I add executable files to the user's PATH? @@ -33,5 +33,5 @@ Dockerfile, and is meant to be built in 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 +Check out the [binder-examples](http://github.com/binder-examples/) GitHub organization for example repositories you can copy & modify for your own use! diff --git a/docs/source/index.rst b/docs/source/index.rst index f37cd4871..84d2975f3 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -2,11 +2,11 @@ jupyter-repo2docker =================== **jupyter-repo2docker** is a tool to build, run, and push Docker -images from source code repositories. repo2docker fetches a repo -(e.g., from GitHub or other locations) and builds a container image based -on the configuration files found in the repo. It can be used to explore a -repository locally by building and executing the constructed image of the -repository. +images from source code repositories. repo2docker fetches a repository +(e.g., from GitHub 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. Please report `Bugs `_, `ask questions `_ or diff --git a/docs/source/install.rst b/docs/source/install.rst index d457789dc..864edc274 100644 --- a/docs/source/install.rst +++ b/docs/source/install.rst @@ -29,7 +29,7 @@ We recommend installing ``repo2docker`` with the ``pip`` tool:: python3 -m pip install jupyter-repo2docker -For infomation on using ``repo2docker``, see :ref:`usage`. +For information on using ``repo2docker``, see :ref:`usage`. Installing from source code --------------------------- @@ -69,10 +69,10 @@ Docker images that can be shared within a JupyterHub deployment. For example, 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 ``requiements.txt`` of the -git repositories you build. +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 diff --git a/docs/source/usage.rst b/docs/source/usage.rst index 4e337eeca..e11514f94 100644 --- a/docs/source/usage.rst +++ b/docs/source/usage.rst @@ -10,15 +10,15 @@ order to run ``repo2docker``. For more information on installing ``repo2docker`` performs two steps: 1. builds a Docker image from a git repo -2. runs a Jupyter server within the image to explore the repo +2. runs a Jupyter server within the image to explore the repository -To ensure you can run the software in your repository, you must +.. To ensure you can run the software in your repository, you must repo2docker is called with this command:: - jupyter-repo2docker + jupyter-repo2docker -where ```` is a URL or path to the source repository. +where ```` is a URL or path to the source repository. For example, use the following to build an image of Peter Norvig's Pytudes_:: @@ -31,21 +31,21 @@ specify the ``branch-name`` or ``commit-hash``:: jupyter-repo2docker https://github.com/norvig/pytudes --ref 9ced85dd9a84859d0767369e58f33912a214a3cf .. tip:: - For reproducibile research, we recommend specifying a commit-hash to - deterministcally build a fixed version of a repository. Not specifying a + For reproducible research, 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. Building the image may take a few minutes. During building, ``repo2docker`` -clones the repository to obtain its contents and inspects the repo for +clones the repository to obtain its contents and inspects the repository for :ref:`configuration files `. By default, ``repo2docker`` will assume you are using Python 3.6 unless you include the version of Python in your :ref:`configuration files `. ``repo2docker`` support is best with -Python 2.7, 3.5, and 3.6. In the case of this repo, a Python version is not -specified in their configuation files and Python 3.6 is installed. +Python 2.7, 3.5, and 3.6. In the case of this repository, a Python version is not +specified in their configuration files and Python 3.6 is installed. Pytudes_ uses a `requirements.txt file `_