Fix: Armada Exceptions docs rendering on RTD

Readthedocs failed to render Armada exceptions with error: > WARNING: autodoc: failed to import exception ... from module > 'armada'; the following exception was raised: No module named 'armada' and others. Trying to add Armada requirements to the installed requirements list, so that Readthedocs has all modules, including those needed for the Armada itself. Cosmetic readability changes: 1. combined all Makefile .PHONY targets into one 2. merged multiple LABEL instructions in Dockerfile into one Change-Id: I3f88fa3abf66e5d6a2f9e57f6f1514a03a0c5a30
2019-08-26 18:51:03 +02:00 · 2019-08-26 18:51:03 +02:00 · 243022d16c
parent 9886cb1a5e
commit 243022d16c
18 changed files with 113 additions and 94 deletions
--- a/.readthedocs.yaml
+++ b/.readthedocs.yaml
@ -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.txt
+    - requirements: requirements.txt
--- a/38
+++ b/38
@ -54,55 +54,43 @@ info:
 	@echo "Docker Version:    ${DOCKER_VERSION}"
 	@echo "Registry:          ${DOCKER_REGISTRY}"

-.PHONY: all
 all: lint charts images

-.PHONY: build
 build: bootstrap
 	$(PYTHON) setup.py install

-.PHONY: bootstrap
 bootstrap:
 	pip install -r requirements.txt

-.PHONY: bootstrap-all
 bootstrap-all: bootstrap
 	pip install -r test-requirements.txt

-.PHONY: check-docker
 check-docker:
 	@if [ -z $$(which docker) ]; then \
 		echo "Missing \`docker\` client which is required for development"; \
 		exit 2; \
 	fi

-.PHONY: check-tox
 check-tox:
 	@if [ -z $$(which tox) ]; then \
 		echo "Missing \`tox\` client which is required for development"; \
 		exit 2; \
 	fi

-.PHONY: images
 images: check-docker build_armada

-.PHONY: docs
 docs: clean build_docs

-.PHONY: build_docs
 build_docs:
 	tox -e docs

-.PHONY: run_images
 run_images: run_armada

-.PHONY: run_armada
 run_armada: build_armada
 	./tools/armada_image_run.sh $(IMAGE)

 _BASE_IMAGE_ARG := $(if $(UBUNTU_BASE_IMAGE),--build-arg FROM="${UBUNTU_BASE_IMAGE}" ,)

-.PHONY: build_armada
 build_armada:
 ifeq ($(USE_PROXY), true)
 	docker build --network host -t $(IMAGE) --label $(LABEL) \
@ -130,11 +118,9 @@ ifeq ($(PUSH_IMAGE), true)
 endif

 # make tools
-.PHONY: protoc
 protoc:
 	@tools/helm-hapi.sh

-.PHONY: clean
 clean:
 	rm -rf build
 	rm -rf doc/build
@ -143,79 +129,67 @@ clean:
 	rm -rf charts/*/charts

 # testing checks
-.PHONY: tests
 tests: check-tox
 	tox

-.PHONY: test-all
 test-all: check-tox helm_lint
 	tox

-.PHONY: test-unit
 test-unit: check-tox
 	tox -e py35

-.PHONY: test-coverage
 test-coverage: check-tox
 	tox -e cover

-.PHONY: test-bandit
 test-bandit: check-tox
 	tox -e bandit

 # Perform auto formatting
-.PHONY: format
 format:
 	tox -e fmt

 # style checks
-.PHONY: lint
 lint: test-pep8 helm_lint

-.PHONY: test-pep8
 test-pep8: check-tox
 	tox -e pep8

 chartbanner:
 	@echo Building charts: $(CHARTS)

-.PHONY: charts
 charts: $(CHARTS)
 	@echo Done building charts.

-.PHONY: helm-init
 helm-init: $(addprefix helm-init-,$(CHARTS))

-.PHONY: helm-init-%
 helm-init-%: helm-serve
 	@echo Initializing chart $*
 	cd charts;if [ -s $*/requirements.yaml ]; then echo "Initializing $*";$(HELM) dep up $*; fi

-.PHONY: helm-serve
 helm-serve: helm-install
 	./tools/helm_tk.sh $(HELM) $(HELM_PIDFILE)

-.PHONY: helm-lint
 helm-lint: $(addprefix helm-lint-,$(CHARTS))

-.PHONY: helm-lint-%
 helm-lint-%: helm-init-%
 	@echo Linting chart $*
 	cd charts;$(HELM) lint $*

-.PHONY: dry-run
 dry-run: clean $(addprefix dry-run-,$(CHARTS))

-.PHONY: dry-run-%
 dry-run-%: helm-lint-%
 	echo Running Dry-Run on chart $*
 	cd charts;$(HELM) template --set pod.resources.enabled=true $*

-.PHONY: $(CHARTS)
 $(CHARTS): $(addprefix dry-run-,$(CHARTS)) chartbanner
 	$(HELM) package -d charts charts/$@

 # Install helm binary
-.PHONY: helm-install
 helm-install:
 	./tools/helm_install.sh $(HELM)
+
+.PHONY: $(CHARTS) all bootstrap bootstrap-all build build_armada \
+  build_docs charts check-docker check-tox clean docs dry-run \
+  dry-run-% format helm-init helm-init-% helm-install helm-lint \
+  helm-lint-% helm-serve images lint protoc run_armada run_images \
+  test-all test-bandit test-coverage test-pep8 tests test-unit
--- a/doc/source/development/getting-started.rst
+++ b/doc/source/development/getting-started.rst
@ -168,7 +168,7 @@ following additional functionality:
  * Role-Based Access Control, allowing Armada to provide authorization around
    specific Armada (and by extension) Tiller functionality.
  * `Keystone`_ authentication and project scoping, providing an additional
-     layer of security.
+    layer of security.

 Before proceeding, ensure that the steps in :ref:`armada-cli-installation`
 have been followed.
--- a/doc/source/operations/documents/v2/document-authoring.rst
+++ b/doc/source/operations/documents/v2/document-authoring.rst
@ -628,7 +628,7 @@ References
 ~~~~~~~~~~

 For working examples please check the examples in our repo
-`here <https://github.com/openstack/airship-armada/tree/master/examples>`__
+`here <https://opendev.org/airship/armada/src/branch/master/examples>`__.


 .. _builtin chart dependencies: https://helm.sh/docs/developing_charts/#chart-dependencies
--- a/doc/source/operations/exceptions/api-exceptions.inc
+++ b/doc/source/operations/exceptions/api-exceptions.inc
@ -18,22 +18,24 @@
 API Exceptions
 --------------

-.. autoexception:: armada.exceptions.api_exceptions.ApiException
+.. currentmodule:: armada.exceptions.api_exceptions
+
+.. autoexception:: ApiException
   :members:
   :show-inheritance:
   :undoc-members:

-.. autoexception:: armada.exceptions.api_exceptions.ClientError
+.. autoexception:: ClientError
   :members:
   :show-inheritance:
   :undoc-members:

-.. autoexception:: armada.exceptions.api_exceptions.ClientForbiddenError
+.. autoexception:: ClientForbiddenError
   :members:
   :show-inheritance:
   :undoc-members:

-.. autoexception:: armada.exceptions.api_exceptions.ClientUnauthorizedError
+.. autoexception:: ClientUnauthorizedError
   :members:
   :show-inheritance:
   :undoc-members:
--- a/doc/source/operations/exceptions/armada-exceptions.inc
+++ b/doc/source/operations/exceptions/armada-exceptions.inc
@ -17,37 +17,39 @@
 Armada Exceptions
 -----------------

-.. autoexception:: armada.exceptions.armada_exceptions.ArmadaTimeoutException
+.. currentmodule:: armada.exceptions.armada_exceptions
+
+.. autoexception:: ArmadaTimeoutException
   :members:
   :show-inheritance:
   :undoc-members:

-.. autoexception:: armada.exceptions.armada_exceptions.ProtectedReleaseException
+.. autoexception:: ProtectedReleaseException
   :members:
   :show-inheritance:
   :undoc-members:

-.. autoexception:: armada.exceptions.armada_exceptions.InvalidValuesYamlException
+.. autoexception:: InvalidValuesYamlException
   :members:
   :show-inheritance:
   :undoc-members:

-.. autoexception:: armada.exceptions.armada_exceptions.InvalidOverrideValuesYamlException
+.. autoexception:: InvalidOverrideValuesYamlException
   :members:
   :show-inheritance:
   :undoc-members:

-.. autoexception:: armada.exceptions.armada_exceptions.ChartDeployException
+.. autoexception:: ChartDeployException
   :members:
   :show-inheritance:
   :undoc-members:

-.. autoexception:: armada.exceptions.armada_exceptions.WaitException
+.. autoexception:: WaitException
   :members:
   :show-inheritance:
   :undoc-members:

-.. autoexception:: armada.exceptions.armada_exceptions.DeploymentLikelyPendingException
+.. autoexception:: DeploymentLikelyPendingException
   :members:
   :show-inheritance:
   :undoc-members:
--- a/doc/source/operations/exceptions/base-exceptions.inc
+++ b/doc/source/operations/exceptions/base-exceptions.inc
@ -17,7 +17,9 @@
 Base Exceptions
 ---------------

-.. autoexception:: armada.exceptions.base_exception.ActionForbidden
+.. currentmodule:: armada.exceptions.base_exception
+
+.. autoexception:: ActionForbidden
   :members:
   :show-inheritance:
   :undoc-members:
--- a/doc/source/operations/exceptions/chartbuilder-exceptions.inc
+++ b/doc/source/operations/exceptions/chartbuilder-exceptions.inc
@ -17,27 +17,29 @@
 Chartbuilder Exceptions
 -----------------------

-.. autoexception:: armada.exceptions.chartbuilder_exceptions.DependencyException
+.. currentmodule:: armada.exceptions.chartbuilder_exceptions
+
+.. autoexception:: DependencyException
   :members:
   :show-inheritance:
   :undoc-members:

-.. autoexception:: armada.exceptions.chartbuilder_exceptions.FilesLoadException
+.. autoexception:: FilesLoadException
   :members:
   :show-inheritance:
   :undoc-members:

-.. autoexception:: armada.exceptions.chartbuilder_exceptions.HelmChartBuildException
+.. autoexception:: HelmChartBuildException
   :members:
   :show-inheritance:
   :undoc-members:

-.. autoexception:: armada.exceptions.chartbuilder_exceptions.IgnoredFilesLoadException
+.. autoexception:: IgnoredFilesLoadException
   :members:
   :show-inheritance:
   :undoc-members:

-.. autoexception:: armada.exceptions.chartbuilder_exceptions.MetadataLoadException
+.. autoexception:: MetadataLoadException
   :members:
   :show-inheritance:
   :undoc-members:
--- a/doc/source/operations/exceptions/k8s-exceptions.inc
+++ b/doc/source/operations/exceptions/k8s-exceptions.inc
@ -17,17 +17,19 @@
 Kubernetes Exceptions
 ---------------------

-.. autoexception:: armada.exceptions.k8s_exceptions.KubernetesErrorEventException
+.. currentmodule:: armada.exceptions.k8s_exceptions
+
+.. autoexception:: KubernetesErrorEventException
   :members:
   :show-inheritance:
   :undoc-members:

-.. autoexception:: armada.exceptions.k8s_exceptions.KubernetesUnknownStreamingEventTypeException
+.. autoexception:: KubernetesUnknownStreamingEventTypeException
   :members:
   :show-inheritance:
   :undoc-members:

-.. autoexception:: armada.exceptions.k8s_exceptions.KubernetesWatchTimeoutException
+.. autoexception:: KubernetesWatchTimeoutException
   :members:
   :show-inheritance:
   :undoc-members:
--- a/doc/source/operations/exceptions/manifest-exceptions.inc
+++ b/doc/source/operations/exceptions/manifest-exceptions.inc
@ -17,7 +17,9 @@
 Manifest Exceptions
 -------------------

-.. autoexception:: armada.exceptions.manifest_exceptions.ManifestException
+.. currentmodule:: armada.exceptions.manifest_exceptions
+
+.. autoexception:: ManifestException
   :members:
   :show-inheritance:
   :undoc-members:
--- a/doc/source/operations/exceptions/override-exceptions.inc
+++ b/doc/source/operations/exceptions/override-exceptions.inc
@ -17,17 +17,19 @@
 Override Exceptions
 -------------------

-.. autoexception:: armada.exceptions.override_exceptions.InvalidOverrideFileException
+.. currentmodule:: armada.exceptions.override_exceptions
+
+.. autoexception:: InvalidOverrideFileException
   :members:
   :show-inheritance:
   :undoc-members:

-.. autoexception:: armada.exceptions.override_exceptions.InvalidOverrideValueException
+.. autoexception:: InvalidOverrideValueException
   :members:
   :show-inheritance:
   :undoc-members:

-.. autoexception:: armada.exceptions.override_exceptions.UnknownDocumentOverrideException
+.. autoexception:: UnknownDocumentOverrideException
   :members:
   :show-inheritance:
   :undoc-members:
--- a/doc/source/operations/exceptions/source-exceptions.inc
+++ b/doc/source/operations/exceptions/source-exceptions.inc
@ -17,27 +17,29 @@
 Source Exceptions
 -----------------

-.. autoexception:: armada.exceptions.source_exceptions.ChartSourceException
+.. currentmodule:: armada.exceptions.source_exceptions
+
+.. autoexception:: ChartSourceException
   :members:
   :show-inheritance:
   :undoc-members:

-.. autoexception:: armada.exceptions.source_exceptions.GitException
+.. autoexception:: GitException
   :members:
   :show-inheritance:
   :undoc-members:

-.. autoexception:: armada.exceptions.source_exceptions.InvalidPathException
+.. autoexception:: InvalidPathException
   :members:
   :show-inheritance:
   :undoc-members:

-.. autoexception:: armada.exceptions.source_exceptions.TarballDownloadException
+.. autoexception:: TarballDownloadException
   :members:
   :show-inheritance:
   :undoc-members:

-.. autoexception:: armada.exceptions.source_exceptions.TarballExtractException
+.. autoexception:: TarballExtractException
   :members:
   :show-inheritance:
   :undoc-members:
--- a/doc/source/operations/exceptions/tiller-exceptions.inc
+++ b/doc/source/operations/exceptions/tiller-exceptions.inc
@ -17,32 +17,34 @@
 Tiller Exceptions
 -----------------

-.. autoexception:: armada.exceptions.tiller_exceptions.ChannelException
+.. currentmodule:: armada.exceptions.tiller_exceptions
+
+.. autoexception:: ChannelException
   :members:
   :show-inheritance:
   :undoc-members:

-.. autoexception:: armada.exceptions.tiller_exceptions.GetReleaseStatusException
+.. autoexception:: GetReleaseStatusException
   :members:
   :show-inheritance:
   :undoc-members:

-.. autoexception:: armada.exceptions.tiller_exceptions.PostUpdateJobCreateException
+.. autoexception:: PostUpdateJobCreateException
   :members:
   :show-inheritance:
   :undoc-members:

-.. autoexception:: armada.exceptions.tiller_exceptions.PreUpdateJobDeleteException
+.. autoexception:: PreUpdateJobDeleteException
   :members:
   :show-inheritance:
   :undoc-members:

-.. autoexception:: armada.exceptions.tiller_exceptions.ReleaseException
+.. autoexception:: ReleaseException
   :members:
   :show-inheritance:
   :undoc-members:

-.. autoexception:: armada.exceptions.tiller_exceptions.TillerListReleasesPagingException
+.. autoexception:: TillerListReleasesPagingException
   :members:
   :show-inheritance:
   :undoc-members:
--- a/doc/source/operations/exceptions/validate-exceptions.inc
+++ b/doc/source/operations/exceptions/validate-exceptions.inc
@ -17,22 +17,24 @@
 Lint (Validate) Exceptions
 --------------------------

-.. autoexception:: armada.exceptions.validate_exceptions.InvalidManifestException
+.. currentmodule:: armada.exceptions.validate_exceptions
+
+.. autoexception:: InvalidManifestException
   :members:
   :show-inheritance:
   :undoc-members:

-.. autoexception:: armada.exceptions.validate_exceptions.InvalidChartDefinitionException
+.. autoexception:: InvalidChartDefinitionException
   :members:
   :show-inheritance:
   :undoc-members:

-.. autoexception:: armada.exceptions.validate_exceptions.InvalidReleaseException
+.. autoexception:: InvalidReleaseException
   :members:
   :show-inheritance:
   :undoc-members:

-.. autoexception:: armada.exceptions.validate_exceptions.InvalidArmadaObjectException
+.. autoexception:: InvalidArmadaObjectException
   :members:
   :show-inheritance:
   :undoc-members:
--- a/doc/source/operations/guide-use-armada.rst
+++ b/doc/source/operations/guide-use-armada.rst
@ -244,7 +244,7 @@ like openstack-keystone.
 .. note::
    The bearer token option is available for the following commands

-    armada apply
-    armada delete
-    armada tiller
+    armada apply,
+    armada delete,
+    armada tiller,
    armada rollback
--- a/images/armada/Dockerfile.opensuse_15
+++ b/images/armada/Dockerfile.opensuse_15
@ -1,12 +1,12 @@
 ARG FROM=opensuse/leap:15.1
 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-armada.readthedocs.org'
-LABEL org.opencontainers.image.source='https://opendev.org/airship/armada'
-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-armada.readthedocs.org' \
+      org.opencontainers.image.source='https://opendev.org/airship/armada' \
+      org.opencontainers.image.vendor='The Airship Authors' \
+      org.opencontainers.image.licenses='Apache-2.0'

 ENV LANG=C.UTF-8
 ENV LC_ALL=C.UTF-8
--- a/images/armada/Dockerfile.ubuntu_bionic
+++ b/images/armada/Dockerfile.ubuntu_bionic
@ -1,12 +1,12 @@
 ARG FROM=ubuntu:18.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-armada.readthedocs.org'
-LABEL org.opencontainers.image.source='https://opendev.org/airship/armada'
-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-armada.readthedocs.org' \
+      org.opencontainers.image.source='https://opendev.org/airship/armada' \
+      org.opencontainers.image.vendor='The Airship Authors' \
+      org.opencontainers.image.licenses='Apache-2.0'

 ENV DEBIAN_FRONTEND noninteractive
 ENV LANG=C.UTF-8
--- a/images/armada/Dockerfile.ubuntu_xenial
+++ b/images/armada/Dockerfile.ubuntu_xenial
@ -1,12 +1,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-armada.readthedocs.org'
-LABEL org.opencontainers.image.source='https://opendev.org/airship/armada'
-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-armada.readthedocs.org' \
+      org.opencontainers.image.source='https://opendev.org/airship/armada' \
+      org.opencontainers.image.vendor='The Airship Authors' \
+      org.opencontainers.image.licenses='Apache-2.0'

 ENV DEBIAN_FRONTEND noninteractive
 ENV LANG=C.UTF-8