Unify publishing of docs, update code convention

Unified publishing to the readthedocs with other Airship projects.
Updated code convention for new documentation location.

Change-Id: If3b634bf04ed36b3f88831f0a276809ce6539b42

.zuul.yaml

@@ -11,63 +11,18 @@
 # limitations under the License.
 
 - project:
+    templates:
+      - docs-on-readthedocs
+    vars:
+      rtd_webhook_id: '38573'
     check:
       jobs:
         - airship-in-a-bottle-linter
-        - airship-in-a-bottle-doc-build
     gate:
       jobs:
         - airship-in-a-bottle-linter
-        - airship-in-a-bottle-doc-build
-    post:
-      jobs:
-        - airship-in-a-bottle-doc-publish
 
 - job:
     name: airship-in-a-bottle-linter
     run: tools/gate/playbooks/zuul-linter.yaml
     nodeset: openstack-helm-single-node
-
-- job:
-    name: airship-in-a-bottle-doc-build
-    description: |
-      Locally build the documentation to check for errors
-    run: tools/gate/playbooks/doc-build.yaml
-    timeout: 300
-    nodeset: openstack-helm-single-node
-
-- job:
-    name: airship-in-a-bottle-doc-publish
-    description: |
-      Publish documentation on airship-drydock.readthedocs.io
-    run: tools/gate/playbooks/doc-publish.yaml
-    secrets:
-      - airship_in_a_bottle_readthedocs
-    timeout: 300
-    nodeset: openstack-helm-single-node
-
-- secret:
-    name: airship_in_a_bottle_readthedocs
-    data:
-      url: !encrypted/pkcs1-oaep
-        - Uml3UChtbn2PP4DbTsf4qC2rStfp07DuWe5NN5pS0KIcOenbD0QX7hvx2MgQkChyKTDTs
-          QhiHolVNAoKCcoHjF8WjFXnk7lVb1Ap4K23J/BFO22OvfziMLEcWfsPIr7a7vHQ/svaiy
-          5YYqHCcJYD43CyzsJKUA7Wjfz+JHu9ZpQQGQY53H/UKxMnou3yuFNjLkCp7jQN7ZAIBX2
-          3IrmstRbhZtJTuQ0+Pncr6t3eSPssc6AU+EG4wlBIp+/MxqsIDkEz3AjWiEkMhxUOEIj6
-          nN9Evswpkyg16u4mDnFJ5vRU73e/cR95I4g5TAXbqD8Ek0PDlL1CXWeyJsabBw/UDhdBz
-          8zGa2o/lke3Wn47asEcs5nyP+DX8rIphXTT8YXjnzrL8Lvj9kaRHqvFcIX29x9gr3diev
-          l6CE7hxPtVLU2PsBWCVjxlkX46OockIWoDJJ4Q9tmpilGPlxlDVhJ485bW0dr8EJFdnGV
-          9eJBGFamrZLiH5h6mOiDtqO1MnuXMLHeA7gnxcRlAC51jh5LzjQFh2wQ9K41T3oZXp+sE
-          TR6pfIsQzTdFl2LMLs+UXRULGcDciJDUxySkTF+W3FEIuMBPN2beL0JFQuPdKbbl0pcpn
-          gCZ/ok3a83q6WMrl68Si6ODJeLSyJ8lRc3m6tADgGekcRfaT2C/BjD6yEvsJiM=
-      token: !encrypted/pkcs1-oaep
-        - SZLvIg3x9of5ORJJsH5BSZVPG5xtoTFWvFaPSAp6T0JIdYcbx03RXnZx3ZAftwQwv908X
-          OycWj3QrIIfXa8rmS7pJ3H3cNBXjB5KISiqWu00u5K2ZOiWt30NrKy3gU0cuyi2iBo38u
-          W034X5Z6onswmzIsvGs7DxxGcSq+RF/2hqAspdzGj7carW3QZoQLkmDDHScnRenH8IB4+
-          XMX/4gO63tqyZGczrd18O+4AlLdRFcAR7ScuVnSpr6KnxyBUfvOec83swS1F60wTniFe5
-          4GwUKcqWG9C4HjoJ4D0+xGO1ZnPd03w1T/mBTU79z86p9IL2rFrJcSwxshKPWDTY+JrmT
-          K9Zn1GYaPJk6oDeHNmJz7b66zcbf8glb2D9KAWeNeCfX+oUPZDw+1ePtGTKV1DcWoQFhp
-          L5IHgyrixkT4hO4LvuRAn0ZRWjV/MWh618HzbgB5785GJlnSnBgeDFcy9+AbmhoWh37C3
-          y7tIF6i8j8Jvlsazmj7XfUeNqLB6V7ibMXc1yKMUBhwMKFLYgAOJbMRtS338Uqj4GCSFa
-          78q40byAbR0O6uHiCtZxrEvAUKz3LJcd+jpKfnSDtnLPAs4je7YUNaCYkGPZnSeaY0XuU
-          2Xjb0r3VK7XNIy8hwC5hj/nb8LGU6Q41mKSSVGF41pK8dLEa4X+LJn21PGDbBI=

Makefile

@@ -13,8 +13,12 @@
 # limitations under the License.
 SHELL = /bin/bash
 
+.PHONY: clean
+clean:
+	rm -rf doc/build
+
 .PHONY: docs
-docs: build_docs
+docs: clean build_docs
 
 .PHONY: build_docs
 build_docs:

README.md

@@ -7,6 +7,9 @@ Helm-deployed containerized workloads.
 Airship is the name for the project formerly known as UCP or the Undercloud
 Platform.
 
+Find more documentation for Airship in a Bottle on
+`Read the Docs <https://airshipit.readthedocs.io/>`_.
+
 To get started, run the following in a fresh Ubuntu 16.04 VM
 (minimum 4vCPU/20GB RAM/32GB disk). This will deploy Airship and Openstack Helm
 (OSH):

doc/source/code-conventions.rst

@@ -143,7 +143,9 @@ Project ``foo``, supporting multiple executable modules ``foo_service``,
 ``foo_cli``, and a shared module ``foo_client`` ::
 
   {root of foo}
-   |- /docs
+   |- /doc
+   |    |- /source
+   |    |- requirements.txt
    |- /etc
    |    |- /foo
    |         |- {sample files}

doc/source/index.rst

@@ -37,9 +37,8 @@ of `OpenStack-Helm`_ which also influences Airship's direction.
 Building this Documentation
 ---------------------------
 
-Use of ``sphinx-build -b html docs/source docs/build`` will build a html
+Use of ``make docs`` will build a html version of this documentation that can
-version of this documentation that can be viewed using a browser at
+be viewed using a browser at doc/build/index.html on the local filesystem.
-docs/build/index.html on the local filesystem.
 
 Specification Details
 ---------------------

tools/gate/playbooks/doc-build.yaml

@@ -1,20 +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: primary
-  tasks:
-    - name: Build documents locally
-      make:
-        chdir: "{{ zuul.project.src_dir }}"
-        target: docs
-      register: result
-      failed_when: result.failed

tools/gate/playbooks/doc-publish.yaml

@@ -1,25 +0,0 @@
-# Copyright 2018 AT&T Intellectual Property. All other rights reserved.
-#
-# 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'
-        body:
-          token: '{{ airship_in_a_bottle_readthedocs.token | trim }}'
-        url: '{{ airship_in_a_bottle_readthedocs.url | trim }}'
-        follow_redirects: all

tox.ini

@@ -2,21 +2,13 @@
 # Allows docs to be built without setup.py having to exist. Requires that
 # usedevelop be False as well (which it is by default).
 skipsdist = True
-envlist = docs
 
 [testenv]
-passenv=HTTP_PROXY HTTPS_PROXY http_proxy https_proxy NO_PROXY no_proxy
+whitelist_externals = rm
-setenv=
-    VIRTUAL_ENV={envdir}
-install_command = pip install {opts} {packages}
-
-[testenv:venv]
-commands = {posargs}
 
 [testenv:docs]
 basepython = python3
 deps = -r{toxinidir}/doc/requirements.txt
-whitelist_externals = rm
 commands =
     rm -rf doc/build
-    sphinx-build -W -b html doc/source doc/build
+    sphinx-build -W -b html doc/source doc/build/html