Test docs and deploy to gh-pages branch

We should definitely be testing docs as part of CI to make sure they build,
which is addressed here. But this change also explores what it could look
like to publish docs to Github Pages rather than ReadTheDocs, so that we can
avoid the additional developer friction of understanding that service and
maintaining user permissions there.

The gh-pages docs are live at:
http://mozilla.github.io/python_moztelemetry/

A few features I notice missing that ReadTheDocs provides:

- hosting multiple versions of the docs, though we don't look to be using this
- download links for PDF, HTML, and Epub
- "Edit on GitHub" links; the gh-pages rendered version links to the content
  on the gh-pages branch rather than on master

The above features are indeed nice to have. RTD is also a fairly
python-specific tool, so if we do value hosting API docs for our projects,
the technique here is a bit more transferable.

This PR is mostly intended to provoke discussion.
I'm totally fine if we decide to close this.

.circleci/config.yml

@@ -20,15 +20,15 @@
 test_settings: &test_settings
   steps:
     - checkout
-    - run:
+    - run: &install_packages
         name: Install system packages
         command: |
           # python-snappy compression relies on C bindings to libsnappy-dev.
           # pyspark needs to run Java, so we install openjdk.
           apt-get update
           apt-get install -y libsnappy-dev openjdk-8-jre-headless
-    - run:
-        name: Run tests
+    - run: &run_tox_environment_matching_circleci_job_name
+        name: Run tox job
         command: |
           pip install tox
           tox -e $CIRCLE_JOB
@@ -74,6 +74,45 @@ jobs:
     docker:
       - image: python:3.7
 
+  docs: &docs_settings
+    docker:
+      - image: python:3.6
+    steps:
+      - checkout
+      - run:
+          <<: *install_packages
+      - run:
+          <<: *run_tox_environment_matching_circleci_job_name
+      - persist_to_workspace:
+          root: docs/_build
+          paths: html
+
+  docs-deploy:
+    docker:
+      - image: node:8.10.0
+    steps:
+      - checkout
+      - attach_workspace:
+          at: docs/_build
+      - run:
+          name: Disable jekyll builds
+          command: touch docs/_build/html/.nojekyll
+      # Needed for write access to the GitHub repository;
+      # see https://circleci.com/docs/2.0/gh-bb-integration/#deployment-keys-and-user-keys
+      - add_ssh_keys:
+          fingerprints:
+            - "bb:e1:fa:08:e2:ff:a4:ed:f9:b0:64:c0:e6:07:0d:08"
+      # The gh-pages npm package looks to be the most widely used utility for
+      # pushing a directory to a git branch;
+      # see https://www.npmjs.com/package/gh-pages
+      - run:
+          name: Deploy docs to gh-pages branch
+          command: |
+            git config user.email "[email protected]"
+            git config user.name "CircleCI docs-deploy job"
+            npm install -g --silent [email protected]
+            gh-pages -d docs/_build/html
+
   lint:
     docker:
       - image: python:3.6
@@ -110,6 +149,7 @@ jobs:
             twine upload dist/*
 
 
+
 ####################
 # Workflows: see https://circleci.com/docs/2.0/workflows/
 ####################
@@ -121,7 +161,15 @@ workflows:
       - py27
       - py35
       - py36
+      - docs
       - lint
+      - docs-deploy:
+          requires:
+            - docs
+          filters:
+            branches:
+              only: master
+
   tagged-deploy:
     jobs:
       - deploy:

README.md

@@ -1,5 +1,4 @@
-
-# python_moztelemetry [![CircleCI Build Status](https://circleci.com/gh/mozilla/python_moztelemetry/tree/master.svg?style=svg)](https://circleci.com/gh/mozilla/python_moztelemetry/tree/master) [![Documentation Status](http://readthedocs.org/projects/python_moztelemetry/badge/?version=latest)](https://python_moztelemetry.readthedocs.io/?badge=latest) [![Updates](https://pyup.io/repos/github/mozilla/python_moztelemetry/shield.svg)](https://pyup.io/repos/github/mozilla/python_moztelemetry/) [![codecov.io](https://codecov.io/github/mozilla/python_moztelemetry/coverage.svg?branch=master)](https://codecov.io/github/mozilla/python_moztelemetry?branch=master)
+# python_moztelemetry [![CircleCI Build Status](https://circleci.com/gh/mozilla/python_moztelemetry/tree/master.svg?style=svg)](https://circleci.com/gh/mozilla/python_moztelemetry/tree/master) [![Updates](https://pyup.io/repos/github/mozilla/python_moztelemetry/shield.svg)](https://pyup.io/repos/github/mozilla/python_moztelemetry/) [![codecov.io](https://codecov.io/github/mozilla/python_moztelemetry/coverage.svg?branch=master)](https://codecov.io/github/mozilla/python_moztelemetry?branch=master)
 
 Spark bindings for Mozilla Telemetry
 

docs/conf.py

@@ -15,12 +15,9 @@
 import sys
 import os
 
-
-on_rtd = os.environ.get('READTHEDOCS') == 'True'
-if not on_rtd:
-    import sphinx_rtd_theme
-    html_theme = 'sphinx_rtd_theme'
-    html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+import sphinx_rtd_theme
+html_theme = 'sphinx_rtd_theme'
+html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the

docs/requirements.txt

@@ -1,3 +1,3 @@
-Sphinx==1.6.3
-sphinx-autobuild==0.6.0
-sphinx-rtd-theme==0.4.0
+Sphinx==1.8.1
+sphinx-autobuild==0.7.1
+sphinx-rtd-theme==0.4.2

tox.ini

@@ -32,3 +32,10 @@ deps =
     flake8
 commands =
     flake8 moztelemetry/ tests/
+
+[testenv:docs]
+description = invoke sphinx-build to build the HTML docs
+deps = -r docs/requirements.txt
+changedir = docs/
+whitelist_externals = make
+commands = make html