Browse Source

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
changes/12/602612/6
Roman Gorshunov 8 months ago
parent
commit
ff024eb81a
8 changed files with 19 additions and 109 deletions
  1. 4
    49
      .zuul.yaml
  2. 5
    1
      Makefile
  3. 3
    0
      README.md
  4. 3
    1
      doc/source/code-conventions.rst
  5. 2
    3
      doc/source/index.rst
  6. 0
    20
      tools/gate/playbooks/doc-build.yaml
  7. 0
    25
      tools/gate/playbooks/doc-publish.yaml
  8. 2
    10
      tox.ini

+ 4
- 49
.zuul.yaml View File

@@ -11,63 +11,18 @@
11 11
 # limitations under the License.
12 12
 
13 13
 - project:
14
+    templates:
15
+      - docs-on-readthedocs
16
+    vars:
17
+      rtd_webhook_id: '38573'
14 18
     check:
15 19
       jobs:
16 20
         - airship-in-a-bottle-linter
17
-        - airship-in-a-bottle-doc-build
18 21
     gate:
19 22
       jobs:
20 23
         - airship-in-a-bottle-linter
21
-        - airship-in-a-bottle-doc-build
22
-    post:
23
-      jobs:
24
-        - airship-in-a-bottle-doc-publish
25 24
 
26 25
 - job:
27 26
     name: airship-in-a-bottle-linter
28 27
     run: tools/gate/playbooks/zuul-linter.yaml
29 28
     nodeset: openstack-helm-single-node
30
-
31
-- job:
32
-    name: airship-in-a-bottle-doc-build
33
-    description: |
34
-      Locally build the documentation to check for errors
35
-    run: tools/gate/playbooks/doc-build.yaml
36
-    timeout: 300
37
-    nodeset: openstack-helm-single-node
38
-
39
-- job:
40
-    name: airship-in-a-bottle-doc-publish
41
-    description: |
42
-      Publish documentation on airship-drydock.readthedocs.io
43
-    run: tools/gate/playbooks/doc-publish.yaml
44
-    secrets:
45
-      - airship_in_a_bottle_readthedocs
46
-    timeout: 300
47
-    nodeset: openstack-helm-single-node
48
-
49
-- secret:
50
-    name: airship_in_a_bottle_readthedocs
51
-    data:
52
-      url: !encrypted/pkcs1-oaep
53
-        - Uml3UChtbn2PP4DbTsf4qC2rStfp07DuWe5NN5pS0KIcOenbD0QX7hvx2MgQkChyKTDTs
54
-          QhiHolVNAoKCcoHjF8WjFXnk7lVb1Ap4K23J/BFO22OvfziMLEcWfsPIr7a7vHQ/svaiy
55
-          5YYqHCcJYD43CyzsJKUA7Wjfz+JHu9ZpQQGQY53H/UKxMnou3yuFNjLkCp7jQN7ZAIBX2
56
-          3IrmstRbhZtJTuQ0+Pncr6t3eSPssc6AU+EG4wlBIp+/MxqsIDkEz3AjWiEkMhxUOEIj6
57
-          nN9Evswpkyg16u4mDnFJ5vRU73e/cR95I4g5TAXbqD8Ek0PDlL1CXWeyJsabBw/UDhdBz
58
-          8zGa2o/lke3Wn47asEcs5nyP+DX8rIphXTT8YXjnzrL8Lvj9kaRHqvFcIX29x9gr3diev
59
-          l6CE7hxPtVLU2PsBWCVjxlkX46OockIWoDJJ4Q9tmpilGPlxlDVhJ485bW0dr8EJFdnGV
60
-          9eJBGFamrZLiH5h6mOiDtqO1MnuXMLHeA7gnxcRlAC51jh5LzjQFh2wQ9K41T3oZXp+sE
61
-          TR6pfIsQzTdFl2LMLs+UXRULGcDciJDUxySkTF+W3FEIuMBPN2beL0JFQuPdKbbl0pcpn
62
-          gCZ/ok3a83q6WMrl68Si6ODJeLSyJ8lRc3m6tADgGekcRfaT2C/BjD6yEvsJiM=
63
-      token: !encrypted/pkcs1-oaep
64
-        - SZLvIg3x9of5ORJJsH5BSZVPG5xtoTFWvFaPSAp6T0JIdYcbx03RXnZx3ZAftwQwv908X
65
-          OycWj3QrIIfXa8rmS7pJ3H3cNBXjB5KISiqWu00u5K2ZOiWt30NrKy3gU0cuyi2iBo38u
66
-          W034X5Z6onswmzIsvGs7DxxGcSq+RF/2hqAspdzGj7carW3QZoQLkmDDHScnRenH8IB4+
67
-          XMX/4gO63tqyZGczrd18O+4AlLdRFcAR7ScuVnSpr6KnxyBUfvOec83swS1F60wTniFe5
68
-          4GwUKcqWG9C4HjoJ4D0+xGO1ZnPd03w1T/mBTU79z86p9IL2rFrJcSwxshKPWDTY+JrmT
69
-          K9Zn1GYaPJk6oDeHNmJz7b66zcbf8glb2D9KAWeNeCfX+oUPZDw+1ePtGTKV1DcWoQFhp
70
-          L5IHgyrixkT4hO4LvuRAn0ZRWjV/MWh618HzbgB5785GJlnSnBgeDFcy9+AbmhoWh37C3
71
-          y7tIF6i8j8Jvlsazmj7XfUeNqLB6V7ibMXc1yKMUBhwMKFLYgAOJbMRtS338Uqj4GCSFa
72
-          78q40byAbR0O6uHiCtZxrEvAUKz3LJcd+jpKfnSDtnLPAs4je7YUNaCYkGPZnSeaY0XuU
73
-          2Xjb0r3VK7XNIy8hwC5hj/nb8LGU6Q41mKSSVGF41pK8dLEa4X+LJn21PGDbBI=

+ 5
- 1
Makefile View File

@@ -13,8 +13,12 @@
13 13
 # limitations under the License.
14 14
 SHELL = /bin/bash
15 15
 
16
+.PHONY: clean
17
+clean:
18
+	rm -rf doc/build
19
+
16 20
 .PHONY: docs
17
-docs: build_docs
21
+docs: clean build_docs
18 22
 
19 23
 .PHONY: build_docs
20 24
 build_docs:

+ 3
- 0
README.md View File

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

+ 3
- 1
doc/source/code-conventions.rst View File

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

+ 2
- 3
doc/source/index.rst View File

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

+ 0
- 20
tools/gate/playbooks/doc-build.yaml View File

@@ -1,20 +0,0 @@
1
-# Licensed under the Apache License, Version 2.0 (the "License");
2
-# you may not use this file except in compliance with the License.
3
-# You may obtain a copy of the License at
4
-#
5
-#     http://www.apache.org/licenses/LICENSE-2.0
6
-#
7
-# Unless required by applicable law or agreed to in writing, software
8
-# distributed under the License is distributed on an "AS IS" BASIS,
9
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
10
-# See the License for the specific language governing permissions and
11
-# limitations under the License.
12
-
13
-- hosts: primary
14
-  tasks:
15
-    - name: Build documents locally
16
-      make:
17
-        chdir: "{{ zuul.project.src_dir }}"
18
-        target: docs
19
-      register: result
20
-      failed_when: result.failed

+ 0
- 25
tools/gate/playbooks/doc-publish.yaml View File

@@ -1,25 +0,0 @@
1
-# Copyright 2018 AT&T Intellectual Property. All other rights reserved.
2
-#
3
-# Licensed under the Apache License, Version 2.0 (the "License");
4
-# you may not use this file except in compliance with the License.
5
-# You may obtain a copy of the License at
6
-#
7
-#     http://www.apache.org/licenses/LICENSE-2.0
8
-#
9
-# Unless required by applicable law or agreed to in writing, software
10
-# distributed under the License is distributed on an "AS IS" BASIS,
11
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12
-# See the License for the specific language governing permissions and
13
-# limitations under the License.
14
-
15
-- hosts: primary
16
-  tasks:
17
-    - name: Publish current merged documents on readthedocs
18
-      no_log: true
19
-      uri:
20
-        method: POST
21
-        body_format: 'json'
22
-        body:
23
-          token: '{{ airship_in_a_bottle_readthedocs.token | trim }}'
24
-        url: '{{ airship_in_a_bottle_readthedocs.url | trim }}'
25
-        follow_redirects: all

+ 2
- 10
tox.ini View File

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

Loading…
Cancel
Save