Merge branch 'master' of github.com:jupyter/repo2docker into feature/launch_script

Author: Joseph Hamman

.gitignore

@@ -9,6 +9,7 @@ MANIFEST
 
 .DS_Store
 .cache
+.pytest_cache
 .coverage
 htmlcov
 

.travis.yml

@@ -15,9 +15,17 @@ install:
 script:
 # cd into tests so CWD being repo2docker does not hide
 # possible issues with MANIFEST.in
-- if [ ${REPO_TYPE} == "r" ]; then cd tests && travis_wait pytest --cov repo2docker
-  -v ${REPO_TYPE}; else cd tests && travis_retry pytest --cov repo2docker -v ${REPO_TYPE};
-  fi
+- pushd tests;
+  if [ ${REPO_TYPE} == "r" ]; then
+    travis_wait pytest --cov repo2docker -v ${REPO_TYPE};
+  else
+    travis_retry pytest --cov repo2docker -v ${REPO_TYPE};
+  fi;
+  popd;
+- pip install -r docs/doc-requirements.txt
+- pushd docs;
+  make html;
+  popd;
 after_success:
 - pip install codecov
 - codecov
@@ -35,8 +43,10 @@ jobs:
         branch: master
 env:
   matrix:
+  - REPO_TYPE=base
   - REPO_TYPE=conda
   - REPO_TYPE=venv
+  - REPO_TYPE=stencila
   - REPO_TYPE=julia
   - REPO_TYPE=r
   - REPO_TYPE=dockerfile

docs/Makefile

@@ -2,7 +2,7 @@
 #
 
 # You can set these variables from the command line.
-SPHINXOPTS    =
+SPHINXOPTS    = -W
 SPHINXBUILD   = python3 -msphinx
 SPHINXPROJ    = repo2docker
 SOURCEDIR     = source

docs/source/config_files.rst

@@ -1,7 +1,9 @@
+.. NOTE: the header characters are different in this file because it is 'included' in another site
+.. see https://raw.githubusercontent.com/jupyterhub/binder/master/doc/using.rst
 .. _config-files:
 
 Configuration Files
-~~~~~~~~~~~~~~~~~~~
+-------------------
 
 ``repo2docker`` looks for configuration files in the repository being built
 to determine how to build it. In general, ``repo2docker`` uses the same
@@ -31,7 +33,7 @@ Below is a list of supported configuration files (roughly in the order of build
    :depth: 1
 
 ``Dockerfile``
-^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~
 
 In the majority of cases, providing your own Dockerfile is not necessary as the base
 images provide core functionality, compact image sizes, and efficient builds. We recommend
@@ -46,7 +48,7 @@ best-practices with Dockerfiles.
 .. _environment-yml:
 
 ``environment.yml``
-^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~
 
 ``environment.yml`` is the standard configuration file used by Anaconda, conda,
 and miniconda that lets you install Python packages.
@@ -63,31 +65,31 @@ a Python version in a ``runtime.txt`` file in addition to your
 ``environment.yml``, your ``runtime.txt`` **will be ignored**.
 
 ``requirements.txt``
-^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~
 
 This specifies a list of Python packages that should be installed in your
 environment. Our
 `requirements.txt example <https://github.com/binder-examples/requirements/blob/master/requirements.txt>`_
 on GitHub shows a typical requirements file.
 
 ``REQUIRE``
-^^^^^^^^^^^
+~~~~~~~~~~~
 
 This specifies a list of Julia packages. Repositories with a  ``REQUIRE`` file
 **must also contain an** ``environment.yml`` **file**.  To see an example of a
 Julia repository with ``REQUIRE`` and ``environment.yml``,
 visit `binder-examples/julia-python <https://github.com/binder-examples/julia-python>`_.
 
 ``install.R``
-^^^^^^^^^^^^^
+~~~~~~~~~~~~~
 
 This is used to install R libraries pinned to a specific snapshot on
 `MRAN <https://mran.microsoft.com/documents/rro/reproducibility>`_.
 To set the date of the snapshot add a runtime.txt_.
 For an example ``install.R`` file, visit our `example install.R file <https://github.com/binder-examples/r/blob/master/install.R>`_.
 
 ``apt.txt``
-^^^^^^^^^^^
+~~~~~~~~~~~
 
 A list of Debian packages that should be installed. The base image used is usually the latest released
 version of Ubuntu.
@@ -97,7 +99,7 @@ We use ``apt.txt``, for example, to install LaTeX in our
 
 
 ``setup.py``
-^^^^^^^^^^^^
+~~~~~~~~~~~~
 
 To install your repository like a Python package, you may include a
 ``setup.py`` file. repo2docker installs ``setup.py`` files by running
@@ -110,7 +112,7 @@ repo2docker **requires configuration files such as** ``environment.yml`` or
 .. _postBuild:
 
 ``postBuild``
-^^^^^^^^^^^^^
+~~~~~~~~~~~~~
 
 A script that can contain arbitrary commands to be run after the whole repository has been built. If you
 want this to be a shell script, make sure the first line is ```#!/bin/bash``.
@@ -136,7 +138,7 @@ equivalent.
 .. _runtime.txt:
 
 ``runtime.txt``
-^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~
 
 This allows you to control the runtime of Python or R.
 

docs/source/deploy.rst

@@ -1,10 +1,10 @@
-.. _usage:
+.. _deploy:
 
 Using ``repo2docker`` as part of your Continuous Integration
 ============================================================
 
-We've created for you the `continuous-build <https://www.github.com/binder-examples/continuous-build/>`_ 
-repository so that you can push a `Docker <https://docs.docker.com/>`_ container 
+We've created for you the `continuous-build <https://www.github.com/binder-examples/continuous-build/>`_
+repository so that you can push a `Docker <https://docs.docker.com/>`_ container
 to `Docker Hub <https://hub.docker.com/>`_ directly from a Github repository
 that has a Jupyter notebook. Here are instructions to do this.
 
@@ -25,7 +25,7 @@ to pull from Docker Hub.
 Step 1. Clone the Repository
 ............................
 First, fork the `continuous-build <https://www.github.com/binder-examples/continuous-build/>`_ Github
-repository to your account, and clone the branch. 
+repository to your account, and clone the branch.
 
    git clone https://www.github.com/<username>/continuous-build
    # or
@@ -35,17 +35,17 @@ repository to your account, and clone the branch.
 Step 2. Choose your Configuration
 .................................
 
-The hidden folder `.circleci/config.yml` has instructions for `CircleCI <https://circleci.com/dashboard/>`_ 
+The hidden folder `.circleci/config.yml` has instructions for `CircleCI <https://circleci.com/dashboard/>`_
 to automatically discover and build your repo2docker jupyter notebook container.
-The default template provided in the repository in this folder will do the most basic steps, 
+The default template provided in the repository in this folder will do the most basic steps,
 including:
 
 1. clone of the repository with the notebook that you specify
 2. build
 3. push to Docker Hub
 
 This repository aims to provide templates for your use.
-If you have a request for a new template, please 
+If you have a request for a new template, please
 `let us know <https://www.github.com/binder-examples/continuous-build/issues/>`_.
 We will add templates as they are requested to do additional tasks like test containers, run
 nbconvert, etc.
@@ -57,7 +57,7 @@ creating a new folder called "myrepo" and then copying the entire folder there.
     mkdir -p myrepo
     cp -R continuous-build/.circleci myrepo/
 
-You would then logically create a Github repository in the "myrepo" folder, 
+You would then logically create a Github repository in the "myrepo" folder,
 add the circleci configuration folder, and continue on to the next steps.
 
     cd myrepo
@@ -69,7 +69,7 @@ Step 3. Docker Hub
 ..................
 Go to `Docker Hub <https://hub.docker.com/>`_, log in, and click the big blue
 button that says "create repository" (not an automated build). Choose an organization
-and name that you like (in the traditional format ``<ORG>/<NAME>``), and 
+and name that you like (in the traditional format ``<ORG>/<NAME>``), and
 remember it! We will be adding it, along with your
 Docker credentials, to be encrypted CircleCI environment variables.
 
@@ -78,12 +78,12 @@ Step 4. Connect to CircleCI
 ...........................
 If you navigate to the main `app page <https://circleci.com/dashboard/>`_ 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 
+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
 the defaults.
 
 Before you push or trigger a build, let's set up the following environment variables.
-Also in the project interface on CirleCi, click the gears icon next to the project 
+Also in the project interface on CirleCi, click the gears icon next to the project
 name to get to your project settings. Under settings, click on the "Environment
 Variables" tab. In this section, you want to define the following:
 
@@ -92,7 +92,7 @@ Variables" tab. In this section, you want to define the following:
 3. ``DOCKER_USER`` and ``DOCKER_PASS`` should be your credentials (to allowing pushing)
 4. ``REPO_NAME`` should be the full Github url (or other) of the repository with the notebook. This doesn't have to coincide with the repository you are using to do the build (e.g., "myrepo" in our example).
 
-If you don't define the ``CONTAINER_NAME`` it will default to be the repository where it is 
+If you don't define the ``CONTAINER_NAME`` it will default to be the repository where it is
 building from, which you should only do if the Docker Hub repository is named equivalently.
 If you don't define either of the variables from step 3. for the Docker credentials, your
 image will build but not be pushed to Docker Hub. Finally, if you don't define the ``REPO_NAME``
@@ -120,7 +120,7 @@ You should then be able to pull your new container, and run it! Here is an examp
 
   docker pull <ORG>/<NAME>
   docker run -it --name repo2docker -p 8888:8888 <ORG>/<NAME> jupyter notebook --ip 0.0.0.0
-  
+
 
 For a pre-built working example, try the following:
 

docs/source/install.rst

@@ -57,19 +57,19 @@ 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:
+.. _jupyterhub_ready:
 
 JupyterHub-ready images
 -----------------------
 
-`JupyterHub <https://jupyterhub.readthedocs.io/en/stable/>`_ allows multiple
+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 <https://github.com/jupyterhub/jupyterhub>`_-ready
+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.
@@ -79,3 +79,5 @@ command to run ``jupyterhub-singleuser`` by adding this line in your
 configuration file::
 
   c.DockerSpawner.cmd = ['jupyterhub-singleuser']
+
+.. _JupyterHub: https://github.com/jupyterhub/jupyterhub

docs/source/usage.rst

@@ -21,7 +21,7 @@ repo2docker is called with this command::
 where ``<URL-or-path to repo>`` is a URL or path to the source repository.
 
 For example, use the following to build an image of Peter Norvig's
-`Pytudes <https://github.com/norvig/pytudes/>`_::
+Pytudes_::
 
   jupyter-repo2docker https://github.com/norvig/pytudes
 
@@ -47,12 +47,14 @@ Python 3.6 unless you include the version of Python in your
 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.
 
-`Pytudes <https://github.com/norvig/pytudes>`_
+Pytudes_
 uses a `requirements.txt file <https://github.com/norvig/pytudes/blob/master/requirements.txt>`_
 to specify its Python environment. ``repo2docker`` uses ``pip`` to install
 dependencies listed in the ``requirement.txt`` in the image. To learn more about
 configuration files in ``repo2docker`` visit :ref:`config-files`.
 
+.. _Pytudes: https://github.com/norvig/pytudes
+
 When the image is built, a message will be output to your terminal::
 
   Copy/paste this URL into your browser when you connect for the first time,

repo2docker/app.py

@@ -18,6 +18,7 @@
 import time
 
 import docker
+from urllib.parse import urlparse
 from docker.utils import kwargs_from_env
 from docker.errors import DockerException
 import escapism
@@ -520,11 +521,26 @@ def start_container(self):
         Returns running container
         """
         client = docker.from_env(version='auto')
+
+        docker_host = os.environ.get('DOCKER_HOST')
+        if docker_host:
+            host_name = urlparse(docker_host).hostname
+        else:
+            host_name = '127.0.0.1'
+        self.hostname = host_name
+
         if not self.run_cmd:
             port = str(self._get_free_port())
             self.port = port
-            run_cmd = ['jupyter', 'notebook', '--ip', '0.0.0.0',
-                       '--port', port]
+            # To use the option --NotebookApp.custom_display_url
+            # make sure the base-notebook image is updated:
+            # docker pull jupyter/base-notebook
+            run_cmd = [
+                'jupyter', 'notebook',
+                '--ip', '0.0.0.0',
+                '--port', port,
+                "--NotebookApp.custom_display_url=http://{}:{}".format(host_name, port),
+            ]
             ports = {'%s/tcp' % port: port}
         else:
             # run_cmd given by user, if port is also given then pass it on
@@ -535,6 +551,7 @@ def start_container(self):
                 ports = {}
         # store ports on self so they can be retrieved in tests
         self.ports = ports
+
         container_volumes = {}
         if self.volumes:
             api_client = docker.APIClient(