Browse Source

Fix: Drydock Exceptions docs rendering on RTD

Readthedocs failed to render Drydock exceptions with error:
> WARNING: autodoc: failed to import exception xxx from module
> 'drydock_provisioner'; the following exception was raised: No module
> named 'drydock_provisioner'

Trying to add Drydock requirements to the installed requirements list,
so that Readthedocs has all modules, including those needed for the
Drydock itself.

Unify docs building by utilizing Zuul docs-on-readthedocs template job.

Cosmetic readability changes:
1. combined all Makefile .PHONY targets into one
2. merged multiple LABEL instructions in Dockerfile into one

Change-Id: I6a9b47cffc66d739968fa886c51e25b1e09ef124
changes/24/678624/7
Roman Gorshunov 2 years ago
parent
commit
161326fe06
41 changed files with 125 additions and 150 deletions
  1. +25
    -0
      .readthedocs.yaml
  2. +7
    -39
      .zuul.yaml
  3. +8
    -28
      Makefile
  4. +0
    -0
      doc/diagrams/architecture.uml
  5. +0
    -0
      doc/diagrams/basic_task_sequence.uml
  6. +0
    -0
      doc/requirements-doc.txt
  7. +0
    -0
      doc/source/API.rst
  8. +0
    -0
      doc/source/_static/.placeholder
  9. +0
    -0
      doc/source/_static/drydock.conf.sample
  10. +0
    -0
      doc/source/_static/policy.yaml.sample
  11. +2
    -2
      doc/source/blueprints/build_data.rst
  12. +0
    -0
      doc/source/blueprints/index.rst
  13. +0
    -0
      doc/source/bootaction.rst
  14. +0
    -0
      doc/source/conf.py
  15. +0
    -0
      doc/source/configuration.rst
  16. +3
    -3
      doc/source/development.rst
  17. +0
    -0
      doc/source/drydock_client.rst
  18. +4
    -2
      doc/source/exceptions/api_error.inc
  19. +5
    -3
      doc/source/exceptions/bootaction_error.inc
  20. +3
    -1
      doc/source/exceptions/build_data_error.inc
  21. +4
    -2
      doc/source/exceptions/client_error.inc
  22. +5
    -3
      doc/source/exceptions/design_error.inc
  23. +7
    -5
      doc/source/exceptions/driver_error.inc
  24. +0
    -0
      doc/source/exceptions/exceptions.rst
  25. +0
    -0
      doc/source/exceptions/index.rst
  26. +4
    -2
      doc/source/exceptions/orchestrator_error.inc
  27. +0
    -0
      doc/source/getting_started.rst
  28. +0
    -0
      doc/source/images/architecture.png
  29. +0
    -0
      doc/source/images/basic_task_sequence.png
  30. +8
    -0
      doc/source/index.rst
  31. +0
    -0
      doc/source/policy-enforcement.rst
  32. +0
    -0
      doc/source/sampleconf.rst
  33. +0
    -0
      doc/source/task.rst
  34. +20
    -20
      doc/source/topology.rst
  35. +0
    -0
      doc/source/troubleshooting/index.rst
  36. +6
    -6
      doc/source/troubleshooting/validations.rst
  37. +3
    -1
      doc/source/validatedesign.rst
  38. +6
    -6
      images/drydock/Dockerfile
  39. +0
    -17
      tools/gate/playbooks/doc-publish.yaml
  40. +0
    -5
      tools/gate/playbooks/omni_test.yaml
  41. +5
    -5
      tox.ini

+ 25
- 0
.readthedocs.yaml View File

@ -0,0 +1,25 @@
# .readthedocs.yml
# Read the Docs configuration file
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
# Required
version: 2
# Build documentation in the doc/ directory with Sphinx
sphinx:
configuration: doc/source/conf.py
# Build documentation with MkDocs
#mkdocs:
# configuration: mkdocs.yml
# Optionally build your docs in additional formats such as PDF and ePub
formats:
- pdf
# Optionally set the version of Python and requirements required to build your docs
python:
version: 3.7
install:
- requirements: doc/requirements-doc.txt
- requirements: requirements-host.txt

+ 7
- 39
.zuul.yaml View File

@ -11,6 +11,11 @@
# limitations under the License.
- project:
templates:
- docs-on-readthedocs
vars:
rtd_webhook_id: '38809'
rtd_project_name: 'airship-drydock'
check:
jobs:
- airship-drydock-omni-test
@ -26,7 +31,6 @@
post:
jobs:
- airship-drydock-doc-publish
- airship-drydock-docker-publish
- drydock-upload-git-mirror
@ -70,7 +74,7 @@
run: tools/gate/playbooks/docker-image-build.yaml
nodeset: airship-drydock-single-node
irrelevant-files:
- '^docs/.*'
- '^doc/.*'
- '^charts/.*'
vars:
publish: false
@ -86,7 +90,7 @@
secrets:
- airship_drydock_quay_creds
irrelevant-files:
- '^docs/.*'
- '^doc/.*'
- '^charts/.*'
vars:
publish: true
@ -97,16 +101,6 @@
static:
- latest
- job:
name: airship-drydock-doc-publish
description: |
Publish documentation on airship-drydock.readthedocs.io
run: tools/gate/playbooks/doc-publish.yaml
secrets:
- airship_drydock_readthedocs
timeout: 300
nodeset: airship-drydock-single-node
- secret:
name: airship_drydock_quay_creds
data:
@ -133,32 +127,6 @@
B1qsfXoY9lVL59lCl4jYLqyGA99Oybi5YKTP8O+IH5Xo7XLOje7K0Vfvh7v8Mcja8pZRG
sgRbPr/10a2g6+s37XofkFEeba7B8fV5h6v/A3tMy7U01rZ2qLBC/4hxrikXT8=
- secret:
name: airship_drydock_readthedocs
data:
url: !encrypted/pkcs1-oaep
- dcOaNb6+3zCSp8rlmaA8U/v8kxzsB9MPqmbfbFSoyCsXOAMvluYSitmF7XpYdZLOXPOvm
+stE6m57dRBDlryymoLHVUxgeAkA/4YR1/78tF8vTLBDbWaLXVLTFBjx6jg17nS9X/UKs
W+UtSA1rVmeoaF8jrxO+c0IJjhgRDchFyPa9s7CnrxUn12IN6IDym0YcUQLxUOFzofm3F
fCtwFY84lRCJhB80jfXuYPlIdxTO3q245JlDvhRm4y6p/qCNljNm/Kw6o6ngKjh0f/CM6
7oFZPsE1XDYWGvR0msq8rjCST6k380vIBeroOqfwRhrjU5YCTgZy2kmw/veY3eGs5bEbb
OBZeIb6mk1+D9bmRbFaTmVns7E+a6Fdz/rrttebmak8aBATQD9sgBnvghFAAHibT4LNdn
ic+eEy/RXqyHqZuIPukQjAF0FgfK7jDqVzB/scx2tpw7lYwpDZM8bOHFNIAC4zRVg66O2
1HPo4egknU8MQRy1FwNm7A91AY2cKZSusfrQlND/vflK27/lxCdHoOYw8JVaGxe02Ac+n
XapfJuj7tAkFF+jeaWamB5CMiC+4M3zsrReB2/kqbxGFXC0nQ9q9AbVg48zCZFxNTVMLj
J5K79voMoMmFoP14trhneFDs1Ki8FOLU1fqU7KrBYrlixI4FJwJ6ljEM9C/OvU=
token: !encrypted/pkcs1-oaep
- i6Js243rxTsL0V1l5UWsJalCiRh3kYs54nBz0M9KKrE5YYdAYkD59jKSPncUeG7V+VTkr
LuwGpI837r/oaYqD7g4ZZhsE/X+xSE1PSdtsSY3t5GZZAPdKG4oSLxl0buTd23JsS6cU4
7IAh4Q28wtaIXg8fZ69KVkGm2f2nXPNKbUH/yPTjFW51yEXI55AClNKzv+mVKLd1PNdCN
USQkmF4fvgFreQym+NkZrUh78YMQI1uNT1e7rhD/jxYCjhZGAEr0Clxiu8UmLIRvxHgc2
2SM99xT8s0/dRudePkSz3zXSagwWvdat8bHqpGHJrakjZvePtGeZrdk20v7JQHt8T3XBp
InfWRB8ad/gDvgpstXiag4EHsJ7tnFuwsFDh+KSYySBjtkbYqY8Rx8lQ5qW/Qgk96LagJ
yzpin6EquBcnnPNTGTYLRF9jtowzbI8G9ItRRWdvkIQSlMQDxROI4bVEnfLHgRMbAKVjF
1oSaiEzMwMHj356qYBS06pBBF3Dr/OCIZNiBy3UU8J6OJt2XchMgy9TVhsGkj+HE092d+
mADSwkA5TpfWJCo8rqTDO8cCXIeiG8kBoxjph5m7YNWUcbuRDQdbga1FjV4lMe9bMyOo5
AJ6O8hl3q7CJElLw6Z7p9vW2wHUf/xr242pZnk70DiMkyXxzJFLLqvRsWctTDc=
- job:
name: drydock-upload-git-mirror
parent: upload-git-mirror


+ 8
- 28
Makefile View File

@ -32,15 +32,12 @@ GO_BUILDER ?= docker.io/golang:1.10-stretch
export
# Build all docker images for this project
.PHONY: images
images: build_drydock
# Run an image locally and exercise simple tests
.PHONY: run_images
run_images: run_drydock
# Run tests
.PHONY: tests
tests: pep8 security docs unit_tests test_baclient
# Install external (not managed by tox/pip) dependencies
@ -49,63 +46,51 @@ external_dep: requirements-host.txt requirements-host-test.txt
touch external_dep
# Run unit and Postgres integration tests in coverage mode
.PHONY: coverage_test
coverage_test: build_drydock
tox -re cover
# Run just unit tests
.PHONY: unit_tests
unit_tests: external_dep
tox -re py35 $(TESTS)
# Run just DB integration tests
.PHONY: db_integration_tests
db_integration_tests: external_dep
tox -re integration $(TESTS)
# Freeze full set of Python requirements
.PHONY: req_freeze
req_freeze:
tox -re freeze
# Run the drydock container and exercise simple tests
.PHONY: run_drydock
run_drydock: build_drydock
tools/drydock_image_run.sh
# It seems CICD expects the target 'drydock' to
# build the chart
.PHONY: drydock
drydock: charts
# Create tgz of the chart
.PHONY: charts
charts: helm-init
$(HELM) dep up charts/drydock
$(HELM) package charts/drydock
# Perform Linting
.PHONY: lint
lint: pep8 helm_lint
# Dry run templating of chart
.PHONY: dry-run
dry-run: helm-init
$(HELM) template --set manifests.secret_ssh_key=true --set conf.ssh.private_key=foo charts/drydock
# Initialize local helm config
.PHONY: helm-init
helm-init: helm-install
tools/helm_tk.sh $(HELM)
# Install helm binary
.PHONY: helm-install
helm-install:
tools/helm_install.sh $(HELM)
# Make targets intended for use by the primary targets above.
.PHONY: build_drydock
build_drydock: external_dep build_baclient
export; tools/drydock_image_build.sh
ifeq ($(PUSH_IMAGE), true)
@ -113,49 +98,44 @@ ifeq ($(PUSH_IMAGE), true)
endif
# Make target for building bootaction signal client
.PHONY: build_baclient
build_baclient: external_dep
docker run -tv $(shell realpath go):/work -v $(shell realpath $(BUILD_DIR)):/build -e GOPATH=/work $(GO_BUILDER) go build -o /build/baclient baclient
# Make target for testing bootaction signal client
.PHONY: test_baclient
test_baclient: external_dep
docker run -tv $(shell realpath go):/work -e GOPATH=/work $(GO_BUILDER) go test -v baclient
.PHONY: docs
docs: clean drydock_docs
.PHONY: security
security: external_dep
tox -e bandit
.PHONY: drydock_docs
drydock_docs: external_dep render_diagrams genpolicy genconfig
tox -e docs
.PHONY: render_diagrams
render_diagrams:
plantuml -v -tpng -o ../source/images docs/diagrams/*.uml
plantuml -v -tpng -o ../source/images doc/diagrams/*.uml
.PHONY: genpolicy
genpolicy:
tox -e genpolicy
.PHONY: genconfig
genconfig:
tox -e genconfig
.PHONY: clean
clean:
rm -rf build
rm -rf docs/build
rm -rf doc/build
rm -rf charts/drydock/charts
rm -rf charts/drydock/requirements.lock
.PHONY: pep8
pep8: external_dep
tox -e pep8
.PHONY: helm_lint
helm_lint: helm-init
$(HELM) lint charts/drydock
.PHONY: build_baclient build_drydock charts clean coverage_test \
db_integration_tests docs drydock drydock_docs dry-run genconfig \
genpolicy helm-init helm-install helm_lint images lint pep8 \
render_diagrams req_freeze run_drydock run_images security \
test_baclient tests unit_tests

docs/diagrams/architecture.uml → doc/diagrams/architecture.uml View File


docs/diagrams/basic_task_sequence.uml → doc/diagrams/basic_task_sequence.uml View File


docs/requirements-doc.txt → doc/requirements-doc.txt View File


docs/source/API.rst → doc/source/API.rst View File


docs/source/_static/.placeholder → doc/source/_static/.placeholder View File


docs/source/_static/drydock.conf.sample → doc/source/_static/drydock.conf.sample View File


docs/source/_static/policy.yaml.sample → doc/source/_static/policy.yaml.sample View File


docs/source/blueprints/build_data.rst → doc/source/blueprints/build_data.rst View File


docs/source/blueprints/index.rst → doc/source/blueprints/index.rst View File


docs/source/bootaction.rst → doc/source/bootaction.rst View File


docs/source/conf.py → doc/source/conf.py View File


docs/source/configuration.rst → doc/source/configuration.rst View File


docs/source/development.rst → doc/source/development.rst View File


docs/source/drydock_client.rst → doc/source/drydock_client.rst View File


docs/source/exceptions/api_error.inc → doc/source/exceptions/api_error.inc View File


docs/source/exceptions/bootaction_error.inc → doc/source/exceptions/bootaction_error.inc View File


docs/source/exceptions/build_data_error.inc → doc/source/exceptions/build_data_error.inc View File


docs/source/exceptions/client_error.inc → doc/source/exceptions/client_error.inc View File


docs/source/exceptions/design_error.inc → doc/source/exceptions/design_error.inc View File


docs/source/exceptions/driver_error.inc → doc/source/exceptions/driver_error.inc View File


docs/source/exceptions/exceptions.rst → doc/source/exceptions/exceptions.rst View File


docs/source/exceptions/index.rst → doc/source/exceptions/index.rst View File


docs/source/exceptions/orchestrator_error.inc → doc/source/exceptions/orchestrator_error.inc View File


docs/source/getting_started.rst → doc/source/getting_started.rst View File


docs/source/images/architecture.png → doc/source/images/architecture.png View File


docs/source/images/basic_task_sequence.png → doc/source/images/basic_task_sequence.png View File


docs/source/index.rst → doc/source/index.rst View File


docs/source/policy-enforcement.rst → doc/source/policy-enforcement.rst View File


docs/source/sampleconf.rst → doc/source/sampleconf.rst View File


docs/source/task.rst → doc/source/task.rst View File


docs/source/topology.rst → doc/source/topology.rst View File


docs/source/troubleshooting/index.rst → doc/source/troubleshooting/index.rst View File


docs/source/troubleshooting/validations.rst → doc/source/troubleshooting/validations.rst View File


docs/source/validatedesign.rst → doc/source/validatedesign.rst View File


+ 6
- 6
images/drydock/Dockerfile View File

@ -15,12 +15,12 @@
ARG FROM=ubuntu:16.04
FROM ${FROM}
LABEL org.opencontainers.image.authors='airship-discuss@lists.airshipit.org, irc://#airshipit@freenode'
LABEL org.opencontainers.image.url='https://airshipit.org'
LABEL org.opencontainers.image.documentation='https://airship-drydock.readthedocs.org'
LABEL org.opencontainers.image.source='https://git.openstack.org/openstack/airship-drydock'
LABEL org.opencontainers.image.vendor='The Airship Authors'
LABEL org.opencontainers.image.licenses='Apache-2.0'
LABEL org.opencontainers.image.authors='airship-discuss@lists.airshipit.org, irc://#airshipit@freenode' \
org.opencontainers.image.url='https://airshipit.org' \
org.opencontainers.image.documentation='https://airship-drydock.readthedocs.org' \
org.opencontainers.image.source='https://git.openstack.org/openstack/airship-drydock' \
org.opencontainers.image.vendor='The Airship Authors' \
org.opencontainers.image.licenses='Apache-2.0'
ARG UBUNTU_REPO=http://archive.ubuntu.com/ubuntu
ARG TRUSTED_UBUNTU_REPO=no


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

@ -1,17 +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: Publish current merged documents on readthedocs
shell: 'set -x && curl -X POST -d "token={{ airship_drydock_readthedocs.token | trim }}" "{{ airship_drydock_readthedocs.url | trim }}"'
register: result

+ 0
- 5
tools/gate/playbooks/omni_test.yaml View File

@ -25,11 +25,6 @@
chdir: "{{ zuul.project.src_dir }}"
target: helm_lint
register: result
- name: Build documents locally
make:
chdir: "{{ zuul.project.src_dir }}"
target: docs
register: result
- name: Execute the make target for security scanning
make:
chdir: "{{ zuul.project.src_dir }}"


+ 5
- 5
tox.ini View File

@ -72,13 +72,13 @@ commands=
basepython=python3
whitelist_externals=tee
sh
commands = sh -c 'oslo-config-generator --config-file=etc/drydock/drydock-config-generator.conf | tee etc/drydock/drydock.conf.sample docs/source/_static/drydock.conf.sample'
commands = sh -c 'oslo-config-generator --config-file=etc/drydock/drydock-config-generator.conf | tee etc/drydock/drydock.conf.sample doc/source/_static/drydock.conf.sample'
[testenv:genpolicy]
basepython=python3
whitelist_externals=tee
sh
commands = sh -c 'oslopolicy-sample-generator --config-file etc/drydock/drydock-policy-generator.conf | tee etc/drydock/policy.yaml.sample docs/source/_static/policy.yaml.sample'
commands = sh -c 'oslopolicy-sample-generator --config-file etc/drydock/drydock-policy-generator.conf | tee etc/drydock/policy.yaml.sample doc/source/_static/policy.yaml.sample'
[testenv:pep8]
basepython=python3
@ -97,9 +97,9 @@ max-line-length=119
[testenv:docs]
basepython=python3
deps=
-rdocs/requirements-doc.txt
-rdoc/requirements-doc.txt
whitelist_externals=rm
recreate=true
commands =
rm -rf docs/build
sphinx-build -b html docs/source docs/build
rm -rf doc/build
sphinx-build -b html doc/source doc/build/html

Loading…
Cancel
Save