From b48b55e3bd76c617c158d381cbd1fd10277aeec1 Mon Sep 17 00:00:00 2001
From: Tim Head <betatim@gmail.com>
Date: Fri, 3 Aug 2018 15:30:48 +0200
Subject: [PATCH] Add documentation build to CI, warnings as errors

Adds a CircleCI job to build the documentation and makes it so that
sphinx warnings are treated as errors.
---
 .circleci/config.yml | 43 +++++++++++++++++++++++++++++++++++++++++++
 docs/Makefile        |  4 ++--
 2 files changed, 45 insertions(+), 2 deletions(-)

diff --git a/.circleci/config.yml b/.circleci/config.yml
index 1a6c4db..1c563da 100644
--- a/.circleci/config.yml
+++ b/.circleci/config.yml
@@ -101,9 +101,52 @@ jobs:
                 command: |
                     python3 .circleci/integration-test.py run 'python3 -m pytest -v /srv/src/integration-tests'
 
+    documentation:
+        docker:
+            # Match target OS of TLJH
+            - image: ubuntu:18.04
+
+        working_directory: ~/repo
+
+        steps:
+            - checkout
+
+            # Setup Python
+            - run:
+                name: install python
+                command: |
+                    apt-get update --yes && apt-get install --yes python3 python3-venv git
+
+            # Download and cache dependencies
+            - restore_cache:
+                key: v1-dependencies-py3.6-sphinx
+
+            - run:
+                name: Setup venv
+                command: |
+                    python3 -m venv /srv/venv
+                    echo 'export PATH=/srv/venv/bin:$PATH' >> $BASH_ENV
+
+            - run:
+                name: install dependencies
+                command: |
+                    pip install sphinx
+
+            - save_cache:
+                paths:
+                    - /srv/venv/
+                key: v1-dependencies-py3.6-sphinx
+
+            - run:
+                name: build documentation
+                command: |
+                    cd docs
+                    make html
+
 workflows:
     version: 2
     all-tests:
         jobs:
             - unit-test
             - integration-test
+            - documentation
diff --git a/docs/Makefile b/docs/Makefile
index 7d07064..5b24fa0 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -2,7 +2,7 @@
 #
 
 # You can set these variables from the command line.
-SPHINXOPTS    =
+SPHINXOPTS    = -W
 SPHINXBUILD   = sphinx-build
 SPHINXPROJ    = TheLittlestJupyterHub
 SOURCEDIR     = .
@@ -17,4 +17,4 @@ help:
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
\ No newline at end of file
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)