From ff024eb81a4af47cc482cc8650d7a460d06f38ea Mon Sep 17 00:00:00 2001 From: Roman Gorshunov Date: Fri, 14 Sep 2018 15:07:07 +0200 Subject: [PATCH] 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 | 53 ++------------------------- Makefile | 6 ++- README.md | 3 ++ doc/source/code-conventions.rst | 4 +- doc/source/index.rst | 5 +-- tools/gate/playbooks/doc-build.yaml | 20 ---------- tools/gate/playbooks/doc-publish.yaml | 25 ------------- tox.ini | 12 +----- 8 files changed, 19 insertions(+), 109 deletions(-) delete mode 100644 tools/gate/playbooks/doc-build.yaml delete mode 100644 tools/gate/playbooks/doc-publish.yaml diff --git a/.zuul.yaml b/.zuul.yaml index 6fa80187..2955b36a 100644 --- a/.zuul.yaml +++ b/.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= diff --git a/Makefile b/Makefile index 48caf188..c6c6a9be 100644 --- a/Makefile +++ b/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: diff --git a/README.md b/README.md index 0b8414bf..6ac327a4 100644 --- a/README.md +++ b/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 `_. + 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): diff --git a/doc/source/code-conventions.rst b/doc/source/code-conventions.rst index d47d1c89..62a5d571 100644 --- a/doc/source/code-conventions.rst +++ b/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} diff --git a/doc/source/index.rst b/doc/source/index.rst index 7bfe69e6..20f21964 100644 --- a/doc/source/index.rst +++ b/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 -version of this documentation that can be viewed using a browser at -docs/build/index.html on the local filesystem. +Use of ``make docs`` will build a html version of this documentation that can +be viewed using a browser at doc/build/index.html on the local filesystem. Specification Details --------------------- diff --git a/tools/gate/playbooks/doc-build.yaml b/tools/gate/playbooks/doc-build.yaml deleted file mode 100644 index b7b2aa16..00000000 --- a/tools/gate/playbooks/doc-build.yaml +++ /dev/null @@ -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 diff --git a/tools/gate/playbooks/doc-publish.yaml b/tools/gate/playbooks/doc-publish.yaml deleted file mode 100644 index b97118e7..00000000 --- a/tools/gate/playbooks/doc-publish.yaml +++ /dev/null @@ -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 diff --git a/tox.ini b/tox.ini index 87e8ece7..a71d469e 100644 --- a/tox.ini +++ b/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 -setenv= - VIRTUAL_ENV={envdir} -install_command = pip install {opts} {packages} - -[testenv:venv] -commands = {posargs} +whitelist_externals = rm [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