(zuul) Add doc build and publish jobs

Add jobs to check that documents build on
check and gate and add a webhook for publishing
to readthedocs.io on post.

Change-Id: Ie6221222ca7be56598c7c7189c9a32817e2c0f85

.gitignore

@@ -4,3 +4,4 @@
 !/doc/source/_static/
 /AUTHORS
 /ChangeLog
+.tox

.zuul.yaml

@@ -0,0 +1,62 @@
+- project:
+    check:
+      jobs:
+        - airship-specs-doc-build
+
+    gate:
+      jobs:
+        - airship-specs-doc-build
+
+    post:
+      jobs:
+        - airship-specs-doc-publish
+
+- nodeset:
+    name: airship-specs-single-node
+    nodes:
+      - name: primary
+        label: ubuntu-xenial
+
+- job:
+    name: airship-specs-doc-build
+    description: |
+      Build documents locally to validate functionality
+    run: gate/playbooks/doc-build.yaml
+    timeout: 900
+    nodeset: airship-specs-single-node
+
+- job:
+    name: airship-specs-doc-publish
+    description: |
+      Publish documentation on airship-specs.readthedocs.io
+    run: gate/playbooks/doc-publish.yaml
+    secrets:
+      - airship_specs_readthedocs
+    timeout: 300
+    nodeset: airship-specs-single-node
+
+- secret:
+    name: airship_specs_readthedocs
+    data:
+      url: !encrypted/pkcs1-oaep
+        - w+FhusV0G8CTwapZN61r2y/X2hqy94gW8DocxV2voO/g0oNm+esDhDUxUR4XaihU+68yL
+          VOhbUbWBAGFs3oHGEPQMzMeSuSIFgctp9v91tLnECulNzmXm44pLr000w61EA2K5H2YRI
+          n9T8vOCBLSOnw4jjxp4I1G0x4uAZv6JNzk112hkwvEAyGsGBm00M88nJiNEHm1luIRt2Q
+          adS3hMFDLvpJ2D3C286bGeuCTbYWVMhPic11rMtMHOigQwrQs/pUWQgh+W06fg6G9Iokn
+          W4bWVVHdRVgRx08eG13Mec8J0Qn+sQhU8/cpZOob/XuYh5+jntTnTqB7Ig/xOY1AY9isy
+          yyaXHcQ/KJ7Px6kDfckIp9rlwnQ8vU53CnTgHaColx/2Qsrzaww/52JvBUGp/61Y/Folu
+          /UF2jnHBSIAT6hRosbkZcLY45J0sDBFcKXBJi9p/5CJTCX+Dg1OKL4hEPX2p1KQzGz+T6
+          uQiRbts5/+RpXE2qgw+RGhORIdLTxokKwyeNf+j0OBGMbho/eIo3gybo0AvPiDRwnBA6F
+          wd4Ub+z3tDGmt+9U8eLcTWRSArqlBFjgf9DMs2u4D1pXAtXXi0QYYF5YgnJWfVHAHVwkO
+          e2n7MMBVs/cHEryC8jYVC9R6yOcaJPY3q3FujQIYLiH0op2cRUeTOIgP4REMwg=
+      token: !encrypted/pkcs1-oaep
+        - JpdDUf95LcYP3ZblOsky/fkScHgOvXeSIS7OpBmWTHRTjWDKi6ZcmFwT1AA5h1oH0dKBC
+          8p40U4zVXfJg2S0aXbo8/VPNLfC2QwZG+vJqsrm+7O3Db2rahwwWqBv4DYsazcrlFtsjZ
+          MA8Qb+NAS68f2gSWbLu3tR8f6wf18J++hc3E3lfa+Qzt2hQDIkjXyPaFWavuzftw6ny4G
+          ViKHn503HEJ3wyGVZ/OzI/F7AOCnGo08QURSD7+1+ktp0FB9Namn6BfaKPKTunaMq1ECV
+          rJIubFmbz3Zv0r+H/eU1sJrFbSY+TcgHC9aSDU2jXfmGsiABptSGPoaqkjio7WSWlRQNg
+          77ws8o1kZTagW9fS1ohJ2lFnEBmWtATY5jaOsvdc6zmzmTpFgyxmaYZrmZMU5X7yO/iDa
+          Sn2CM2II6BecLtVi3VQTBCVEGqo9JVqD8NU1dDz5arz56+p+QBLv4YpjhHLe4A3Z5FmOo
+          qYrJiRZpx0gVgxJiWx58XJJ3UvlN9LpjCxRoySlL9KPYJFzRmbDUSuduf9scJ5EbzsaQ/
+          fIxmjGBs9LKjo+2wppRtabVQK+YyQ5KZW+fMzheAqwJt7uB1aJ5XMS8UZWDxH6/bgW8RH
+          MQK7Hi+9HD8GWsTm5YcdXuIZmhw27/iFoY0dcgBYiIrhMHwDXi9MzaZSfBeuzY=

Makefile

@@ -2,19 +2,14 @@
 #
 
 # You can set these variables from the command line.
+# TODO: Incorporate these vars into tox file
 SPHINXOPTS    = -a -E -W
 SPHINXBUILD   = sphinx-build
 SPHINXPROJ    = airship-specs
 SOURCEDIR     = doc/source
 BUILDDIR      = doc/build
 
-# Put it first so that "make" without argument is like "make help".
-help:
-	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+docs:
+	tox
 
-.PHONY: help Makefile
-
-# 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)
+%: docs

doc/requirements.txt

@@ -0,0 +1,2 @@
+sphinx==1.7.6
+sphinx_rtd_theme==0.4.1

doc/source/conf.py

@@ -5,6 +5,7 @@
 # This file does only contain a selection of the most common options. For a
 # full list see the documentation:
 # http://www.sphinx-doc.org/en/master/config
+import sphinx_rtd_theme
 
 # -- Path setup --------------------------------------------------------------
 
@@ -74,7 +75,8 @@ pygments_style = 'sphinx'
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'alabaster'
+html_theme = "sphinx_rtd_theme"
+html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
@@ -152,4 +154,4 @@ texinfo_documents = [
     (master_doc, 'airship-specs', 'airship-specs Documentation',
      author, 'airship-specs', 'One line description of project.',
      'Miscellaneous'),
-]
+]

gate/playbooks/doc-build.yaml

@@ -0,0 +1,23 @@
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# Combine several test tasks into a single playbook
+# to minimize Zuul node consumption
+
+- hosts: primary
+  tasks:
+    - name: Build documents locally
+      make:
+        chdir: "{{ zuul.project.src_dir }}"
+        target: docs
+      register: result
+

gate/playbooks/doc-publish.yaml

@@ -0,0 +1,23 @@
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+- hosts: primary
+  tasks:
+    - name: Publish current merged documents on readthedocs
+      no_log: true
+      uri:
+        method: 'POST'
+        body_format: 'json'
+        url: '{{ airship_specs_readthedocs.url | trim}}'
+        body:
+          token: '{{ airship_specs_readthedocs.token | trim }}'
+      register: result

tox.ini

@@ -0,0 +1,15 @@
+[tox]
+envlist = docs
+skipsdist = True
+
+[testenv]
+basepython=python3
+deps=
+  -rdoc/requirements.txt
+
+[testenv:docs]
+whitelist_externals=
+  rm
+commnds=
+  rm -rf doc/build
+  sphinx-build -b html doc/source doc/build -a -E -W