Replace venv with tox for documentation builds

OpenStack infra has created Zuul project templates that will enable us
to push our documentation to Read the Docs and the Airship website.
While adding a tox file to this project is not ideal, it appears to be
the only way to leverage these jobs at the moment.

This change adds a tox.ini file to airshipctl to build our documentation
and removes the venv solution. The Airship Working Committee will work
with the OpenStack infra team, if possible, to make the publish jobs
more flexible in the future and remove the tox.ini file.

Change-Id: I274cf69a7c79e0aad1d4c9b1decfaf5630f0b18f
Signed-off-by: Drew Walters <andrew.walters@att.com>

.gitignore

@@ -22,4 +22,4 @@ bin/
 .vscode/
 
 # Sphinx build venv
-venv/
+.tox/

Makefile

@@ -38,13 +38,6 @@ PROXY               ?= http://proxy.foo.com:8000
 NO_PROXY            ?= localhost,127.0.0.1,.svc.cluster.local
 USE_PROXY           ?= false
 
-# Sphinx document options
-PYTHON_EXECUTABLE   := python3
-SPHINXBUILD         ?= sphinx-build
-SOURCEDIR           = docs/source
-BUILDDIR            = docs/build/html
-REQUIREMENTSTXT     := docs/requirements.txt
-
 # Godoc server options
 GD_PORT             ?= 8080
 
@@ -153,11 +146,7 @@ clean:
 
 .PHONY: docs
 docs:
-	@$(PYTHON_EXECUTABLE) -m venv venv
+	tox
-	source ./venv/bin/activate
-	@$(PYTHON_EXECUTABLE) -m pip install -r ${REQUIREMENTSTXT}
-	@$(SPHINXBUILD) "$(SOURCEDIR)" "$(BUILDDIR)"
-	rm -rf venv
 
 .PHONY: godoc
 godoc:

playbooks/airship-airshipctl-build-docs.yaml

@@ -1,18 +0,0 @@
-# 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: all
-  become: yes
-  roles:
-    - ensure-python
-    - airshipctl-build-docs
-    - fetch-sphinx-output

roles/airshipctl-build-docs/tasks/main.yaml

@@ -1,16 +0,0 @@
-# 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.
-
-- name: Buid airshipctl Docs
-  make:
-    chdir: "{{ zuul.project.src_dir }}"
-    target: docs

tox.ini

@@ -0,0 +1,18 @@
+[tox]
+envlist = docs
+skipsdist = true
+
+[testenv]
+setenv = VIRTUAL_ENV={envdir}
+         LANGUAGE=en_US
+         LC_ALL=en_US.utf-8
+passenv = http_proxy HTTP_PROXY https_proxy HTTPS_PROXY no_proxy NO_PROXY
+
+[testenv:docs]
+basepython = python3
+whitelist_externals = rm
+deps =
+    -r{toxinidir}/docs/requirements.txt
+commands =
+    rm -rf docs/build
+    sphinx-build docs/source docs/build/html

zuul.d/jobs.yaml

@@ -15,14 +15,6 @@
     run: tests/ansible/role-test-runner.yaml
     nodeset: airship-airshipctl-single-node
 
-- job:
-    name: airship-airshipctl-build-docs
-    nodeset: airship-airshipctl-single-node
-    run: playbooks/airship-airshipctl-build-docs.yaml
-    vars:
-      sphinx_build_dir: docs/build
-      python_version: 3.7
-
 - job:
     name: airship-airshipctl-lint-unit
     pre-run: playbooks/airship-airshipctl-deploy-docker.yaml

zuul.d/projects.yaml

@@ -11,16 +11,17 @@
 # limitations under the License.
 
 - project:
+    templates:
+      - docs-on-readthedocs
     vars:
-      # NOTE(drewwalters96): These variables are required for the documentation promotion job.
+      rtd_project_name: airship-airshipctl
-      download_artifact_job: airship-airshipctl-build-docs
+      rtd_webhook_id: 112688
-      download_artifact_pipeline: gate
+      sphinx_build_dir: docs/build
     check:
       jobs:
         - airship-airshipctl-roles-test:
             files:
               - "roles/*"
-        - airship-airshipctl-build-docs
         - airship-airshipctl-lint-unit
         - airship-airshipctl-build-image
 #        - airship-airshipctl-functional-existing-k8s TODO: Enable this when functional tests exist, and a cluster is up
@@ -28,7 +29,6 @@
         - airship-airshipctl-32GB-gate-test
     gate:
       jobs:
-        - airship-airshipctl-build-docs
         - airship-airshipctl-lint-unit
         - airship-airshipctl-build-image
 #        - airship-airshipctl-functional-existing-k8s TODO: Enable this when functional tests exist, and a cluster is up