From 243022d16cec299e917403eaa14d5bce188ffec4 Mon Sep 17 00:00:00 2001 From: Roman Gorshunov Date: Mon, 26 Aug 2019 18:51:03 +0200 Subject: [PATCH] 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 --- .readthedocs.yaml | 25 ++++++++++++ Makefile | 38 +++---------------- doc/source/development/getting-started.rst | 2 +- .../documents/v2/document-authoring.rst | 2 +- .../operations/exceptions/api-exceptions.inc | 10 +++-- .../exceptions/armada-exceptions.inc | 16 ++++---- .../operations/exceptions/base-exceptions.inc | 4 +- .../exceptions/chartbuilder-exceptions.inc | 12 +++--- .../operations/exceptions/k8s-exceptions.inc | 8 ++-- .../exceptions/manifest-exceptions.inc | 4 +- .../exceptions/override-exceptions.inc | 8 ++-- .../exceptions/source-exceptions.inc | 12 +++--- .../exceptions/tiller-exceptions.inc | 14 ++++--- .../exceptions/validate-exceptions.inc | 10 +++-- doc/source/operations/guide-use-armada.rst | 6 +-- images/armada/Dockerfile.opensuse_15 | 12 +++--- images/armada/Dockerfile.ubuntu_bionic | 12 +++--- images/armada/Dockerfile.ubuntu_xenial | 12 +++--- 18 files changed, 113 insertions(+), 94 deletions(-) create mode 100644 .readthedocs.yaml diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 00000000..9e9c1463 --- /dev/null +++ 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 diff --git a/Makefile b/Makefile index d7820382..0db5bcc4 100644 --- a/Makefile +++ b/Makefile @@ -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 diff --git a/doc/source/development/getting-started.rst b/doc/source/development/getting-started.rst index f5bc2d57..fa4f8f78 100644 --- 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. diff --git a/doc/source/operations/documents/v2/document-authoring.rst b/doc/source/operations/documents/v2/document-authoring.rst index f110ec34..841d265c 100644 --- 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 `__ +`here `__. .. _builtin chart dependencies: https://helm.sh/docs/developing_charts/#chart-dependencies diff --git a/doc/source/operations/exceptions/api-exceptions.inc b/doc/source/operations/exceptions/api-exceptions.inc index 7cc438bb..af45c3c4 100644 --- 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: diff --git a/doc/source/operations/exceptions/armada-exceptions.inc b/doc/source/operations/exceptions/armada-exceptions.inc index 87ca4989..49dff73d 100644 --- 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: diff --git a/doc/source/operations/exceptions/base-exceptions.inc b/doc/source/operations/exceptions/base-exceptions.inc index 3d01f4fa..69e145e4 100644 --- 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: diff --git a/doc/source/operations/exceptions/chartbuilder-exceptions.inc b/doc/source/operations/exceptions/chartbuilder-exceptions.inc index 5d0a8154..44c5ea10 100644 --- 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: diff --git a/doc/source/operations/exceptions/k8s-exceptions.inc b/doc/source/operations/exceptions/k8s-exceptions.inc index ec8df420..5a918687 100644 --- 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: diff --git a/doc/source/operations/exceptions/manifest-exceptions.inc b/doc/source/operations/exceptions/manifest-exceptions.inc index bd7239f8..5a665402 100644 --- 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: diff --git a/doc/source/operations/exceptions/override-exceptions.inc b/doc/source/operations/exceptions/override-exceptions.inc index eda1242b..8363d188 100644 --- 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: diff --git a/doc/source/operations/exceptions/source-exceptions.inc b/doc/source/operations/exceptions/source-exceptions.inc index 932d5815..8afc9a71 100644 --- 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: diff --git a/doc/source/operations/exceptions/tiller-exceptions.inc b/doc/source/operations/exceptions/tiller-exceptions.inc index 4b1d63c7..a175f592 100644 --- 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: diff --git a/doc/source/operations/exceptions/validate-exceptions.inc b/doc/source/operations/exceptions/validate-exceptions.inc index 1380d506..e880e0de 100644 --- 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: diff --git a/doc/source/operations/guide-use-armada.rst b/doc/source/operations/guide-use-armada.rst index 290fe67d..09cbf292 100644 --- 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 diff --git a/images/armada/Dockerfile.opensuse_15 b/images/armada/Dockerfile.opensuse_15 index 4c63ff71..87ba5eb0 100644 --- 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 diff --git a/images/armada/Dockerfile.ubuntu_bionic b/images/armada/Dockerfile.ubuntu_bionic index b26aa5ef..9909ba64 100644 --- 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 diff --git a/images/armada/Dockerfile.ubuntu_xenial b/images/armada/Dockerfile.ubuntu_xenial index 4bc11782..40998381 100644 --- 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