Merge pull request #372 from betatim/add-docs-to-ci

Fix warnings in the documentation build and add to CI

Author: willingc

.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

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/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,