docs: add publish script

Makefile

@@ -1,8 +1,13 @@
-VENV := build/venv
 DOCS_OUTPUT_DIR ?= generated/docs
+DOCS_PUBLISH_DIR ?= ../envoy-docs
 
 .PHONY: docs
 docs:
 	rm -fr generated/docs
 	mkdir -p generated/docs
 	docs/build.sh $(DOCS_OUTPUT_DIR)
+
+.PHONY: publish_docs
+publish_docs: docs
+	docs/publish.sh $(DOCS_OUTPUT_DIR) $(DOCS_PUBLISH_DIR)
+

docs/README.md

@@ -0,0 +1,8 @@
+How to publish new docs:
+
+* The docs are contained in the gh-pages branch in the repo.
+* Clone a fresh copy of the repo into a parallel envoy-docs directory.
+* Run: `make publish_docs`
+* Run: `cd ../envoy-docs`
+* Verify the latest commit looks OK
+* Run: `git push origin gh-pages:gh-pages`

docs/conf.py

@@ -15,6 +15,7 @@
 import sphinx_rtd_theme
 import sys
 import os
+import git
 
 # 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
@@ -55,11 +56,14 @@
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
-#
+
+repo = git.Repo('../')
+last_commit = str(repo.head.commit)[:6]
+
 # The short X.Y version.
-version = u'1.0.0'
+version = u'1.1.0-' + last_commit
 # The full version, including alpha/beta/rc tags.
-release = u'1.0.0'
+release = u'1.1.0' + last_commit
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

docs/publish.sh

@@ -0,0 +1,21 @@
+#!/bin/bash
+
+set -e
+
+DOCS_DIR=$1
+PUBLISH_DIR=$2
+BUILD_SHA=`git rev-parse HEAD`
+
+if [[ ! -d $PUBLISH_DIR ]]; then
+    echo "$PUBLISH_DIR does not exist. Clone a fresh envoy repo."
+fi
+
+git -C $PUBLISH_DIR fetch
+git -C $PUBLISH_DIR checkout -B gh-pages origin/gh-pages
+rm -fr $PUBLISH_DIR/*
+cp -r $DOCS_DIR/* $PUBLISH_DIR
+git -C $PUBLISH_DIR add .
+git -C $PUBLISH_DIR commit -m "docs @$BUILD_SHA"
+
+echo
+echo "*** YOU MUST MANUALLY PUSH the gh-pages branch after verifying the commit ***"

docs/requirements.txt

@@ -1,3 +1,4 @@
 sphinx==1.4.5
 sphinx_rtd_theme==0.1.9
 sphinxcontrib-httpdomain==1.5.0
+GitPython==2.0.8