From 161326fe06c1e9820e463373c45f9265cac1eaf5 Mon Sep 17 00:00:00 2001 From: Roman Gorshunov Date: Mon, 26 Aug 2019 19:27:03 +0200 Subject: [PATCH] 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 --- .readthedocs.yaml | 25 ++++++++++ .zuul.yaml | 46 +++--------------- Makefile | 36 +++----------- {docs => doc}/diagrams/architecture.uml | 0 .../diagrams/basic_task_sequence.uml | 0 {docs => doc}/requirements-doc.txt | 0 {docs => doc}/source/API.rst | 0 {docs => doc}/source/_static/.placeholder | 0 .../source/_static/drydock.conf.sample | 0 .../source/_static/policy.yaml.sample | 0 .../source/blueprints/build_data.rst | 4 +- {docs => doc}/source/blueprints/index.rst | 0 {docs => doc}/source/bootaction.rst | 0 {docs => doc}/source/conf.py | 0 {docs => doc}/source/configuration.rst | 0 {docs => doc}/source/development.rst | 6 +-- {docs => doc}/source/drydock_client.rst | 0 {docs => doc}/source/exceptions/api_error.inc | 6 ++- .../source/exceptions/bootaction_error.inc | 8 +-- .../source/exceptions/build_data_error.inc | 4 +- .../source/exceptions/client_error.inc | 6 ++- .../source/exceptions/design_error.inc | 8 +-- .../source/exceptions/driver_error.inc | 12 +++-- .../source/exceptions/exceptions.rst | 0 {docs => doc}/source/exceptions/index.rst | 0 .../source/exceptions/orchestrator_error.inc | 6 ++- {docs => doc}/source/getting_started.rst | 0 {docs => doc}/source/images/architecture.png | Bin .../source/images/basic_task_sequence.png | Bin {docs => doc}/source/index.rst | 8 +++ {docs => doc}/source/policy-enforcement.rst | 0 {docs => doc}/source/sampleconf.rst | 0 {docs => doc}/source/task.rst | 0 {docs => doc}/source/topology.rst | 40 +++++++-------- .../source/troubleshooting/index.rst | 0 .../source/troubleshooting/validations.rst | 12 ++--- {docs => doc}/source/validatedesign.rst | 4 +- images/drydock/Dockerfile | 12 ++--- tools/gate/playbooks/doc-publish.yaml | 17 ------- tools/gate/playbooks/omni_test.yaml | 5 -- tox.ini | 10 ++-- 41 files changed, 125 insertions(+), 150 deletions(-) create mode 100644 .readthedocs.yaml rename {docs => doc}/diagrams/architecture.uml (100%) rename {docs => doc}/diagrams/basic_task_sequence.uml (100%) rename {docs => doc}/requirements-doc.txt (100%) rename {docs => doc}/source/API.rst (100%) rename {docs => doc}/source/_static/.placeholder (100%) rename {docs => doc}/source/_static/drydock.conf.sample (100%) rename {docs => doc}/source/_static/policy.yaml.sample (100%) rename {docs => doc}/source/blueprints/build_data.rst (97%) rename {docs => doc}/source/blueprints/index.rst (100%) rename {docs => doc}/source/bootaction.rst (100%) rename {docs => doc}/source/conf.py (100%) rename {docs => doc}/source/configuration.rst (100%) rename {docs => doc}/source/development.rst (97%) rename {docs => doc}/source/drydock_client.rst (100%) rename {docs => doc}/source/exceptions/api_error.inc (87%) rename {docs => doc}/source/exceptions/bootaction_error.inc (81%) rename {docs => doc}/source/exceptions/build_data_error.inc (90%) rename {docs => doc}/source/exceptions/client_error.inc (85%) rename {docs => doc}/source/exceptions/design_error.inc (82%) rename {docs => doc}/source/exceptions/driver_error.inc (75%) rename {docs => doc}/source/exceptions/exceptions.rst (100%) rename {docs => doc}/source/exceptions/index.rst (100%) rename {docs => doc}/source/exceptions/orchestrator_error.inc (86%) rename {docs => doc}/source/getting_started.rst (100%) rename {docs => doc}/source/images/architecture.png (100%) rename {docs => doc}/source/images/basic_task_sequence.png (100%) rename {docs => doc}/source/index.rst (95%) rename {docs => doc}/source/policy-enforcement.rst (100%) rename {docs => doc}/source/sampleconf.rst (100%) rename {docs => doc}/source/task.rst (100%) rename {docs => doc}/source/topology.rst (98%) rename {docs => doc}/source/troubleshooting/index.rst (100%) rename {docs => doc}/source/troubleshooting/validations.rst (83%) rename {docs => doc}/source/validatedesign.rst (88%) delete mode 100644 tools/gate/playbooks/doc-publish.yaml diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 00000000..bfc411d5 --- /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-doc.txt + - requirements: requirements-host.txt diff --git a/.zuul.yaml b/.zuul.yaml index 326bdf94..b095eb35 100644 --- a/.zuul.yaml +++ b/.zuul.yaml @@ -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 diff --git a/Makefile b/Makefile index 7401541f..792a19cf 100644 --- a/Makefile +++ b/Makefile @@ -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 diff --git a/docs/diagrams/architecture.uml b/doc/diagrams/architecture.uml similarity index 100% rename from docs/diagrams/architecture.uml rename to doc/diagrams/architecture.uml diff --git a/docs/diagrams/basic_task_sequence.uml b/doc/diagrams/basic_task_sequence.uml similarity index 100% rename from docs/diagrams/basic_task_sequence.uml rename to doc/diagrams/basic_task_sequence.uml diff --git a/docs/requirements-doc.txt b/doc/requirements-doc.txt similarity index 100% rename from docs/requirements-doc.txt rename to doc/requirements-doc.txt diff --git a/docs/source/API.rst b/doc/source/API.rst similarity index 100% rename from docs/source/API.rst rename to doc/source/API.rst diff --git a/docs/source/_static/.placeholder b/doc/source/_static/.placeholder similarity index 100% rename from docs/source/_static/.placeholder rename to doc/source/_static/.placeholder diff --git a/docs/source/_static/drydock.conf.sample b/doc/source/_static/drydock.conf.sample similarity index 100% rename from docs/source/_static/drydock.conf.sample rename to doc/source/_static/drydock.conf.sample diff --git a/docs/source/_static/policy.yaml.sample b/doc/source/_static/policy.yaml.sample similarity index 100% rename from docs/source/_static/policy.yaml.sample rename to doc/source/_static/policy.yaml.sample diff --git a/docs/source/blueprints/build_data.rst b/doc/source/blueprints/build_data.rst similarity index 97% rename from docs/source/blueprints/build_data.rst rename to doc/source/blueprints/build_data.rst index dfa8b92c..45310288 100644 --- a/docs/source/blueprints/build_data.rst +++ b/doc/source/blueprints/build_data.rst @@ -38,8 +38,8 @@ described by the following fields. * Task - The Drydock Task ID that initiated the collection. * Node - The node on which the data is collected. * Generator - A description of what generated the data. If it was a command line tool, - the full command line. If it was something else, then a solid description - such as an API endpoint. + the full command line. If it was something else, then a solid description + such as an API endpoint. * Format - The format that the collected data is being persisted as. Post-collection, the build data will be accessible in two ways diff --git a/docs/source/blueprints/index.rst b/doc/source/blueprints/index.rst similarity index 100% rename from docs/source/blueprints/index.rst rename to doc/source/blueprints/index.rst diff --git a/docs/source/bootaction.rst b/doc/source/bootaction.rst similarity index 100% rename from docs/source/bootaction.rst rename to doc/source/bootaction.rst diff --git a/docs/source/conf.py b/doc/source/conf.py similarity index 100% rename from docs/source/conf.py rename to doc/source/conf.py diff --git a/docs/source/configuration.rst b/doc/source/configuration.rst similarity index 100% rename from docs/source/configuration.rst rename to doc/source/configuration.rst diff --git a/docs/source/development.rst b/doc/source/development.rst similarity index 97% rename from docs/source/development.rst rename to doc/source/development.rst index 009460eb..4e4d739b 100644 --- a/docs/source/development.rst +++ b/doc/source/development.rst @@ -141,8 +141,8 @@ a proxy or for geneting the Docker image with custom tags. * ``IMAGE_PREFIX`` - Defaults to ``airshipit``, the registry organization to push images into * ``IMAGE_TAG`` - Defaults to ``dev``, a tag to apply to the image * ``PUSH_IMAGE`` - Defaults to ``false``, set to ``true`` if you want the build process to also - push the image. Likely will require you have previously run ``docker login``. + push the image. Likely will require you have previously run ``docker login``. * ``PROXY`` - A HTTP/HTTPS proxy server to add to the image build environment. Required if you - are building the image behind a proxy. + are building the image behind a proxy. * ``USE_PROXY`` - Defaults to ``false``, set to ``true`` to include the ``PROXY`` configuration - above in the build. + above in the build. diff --git a/docs/source/drydock_client.rst b/doc/source/drydock_client.rst similarity index 100% rename from docs/source/drydock_client.rst rename to doc/source/drydock_client.rst diff --git a/docs/source/exceptions/api_error.inc b/doc/source/exceptions/api_error.inc similarity index 87% rename from docs/source/exceptions/api_error.inc rename to doc/source/exceptions/api_error.inc index b49ba5ca..db6827e4 100644 --- a/docs/source/exceptions/api_error.inc +++ b/doc/source/exceptions/api_error.inc @@ -17,12 +17,14 @@ API Errors ---------- -.. autoexception:: drydock_provisioner.error.ClientError +.. currentmodule:: drydock_provisioner.error + +.. autoexception:: ClientError :members: :show-inheritance: :undoc-members: -.. autoexception:: drydock_provisioner.error.InvalidFormat +.. autoexception:: InvalidFormat :members: :show-inheritance: :undoc-members: diff --git a/docs/source/exceptions/bootaction_error.inc b/doc/source/exceptions/bootaction_error.inc similarity index 81% rename from docs/source/exceptions/bootaction_error.inc rename to doc/source/exceptions/bootaction_error.inc index ddb1796f..c423ac91 100644 --- a/docs/source/exceptions/bootaction_error.inc +++ b/doc/source/exceptions/bootaction_error.inc @@ -18,17 +18,19 @@ Bootaction Errors ----------------- -.. autoexception:: drydock_provisioner.error.InvalidAssetLocation +.. currentmodule:: drydock_provisioner.error + +.. autoexception:: InvalidAssetLocation :members: :show-inheritance: :undoc-members: -.. autoexception:: drydock_provisioner.error.PipelineFailure +.. autoexception:: PipelineFailure :members: :show-inheritance: :undoc-members: -.. autoexception:: drydock_provisioner.error.UnknownPipelineSegment +.. autoexception:: UnknownPipelineSegment :members: :show-inheritance: :undoc-members: diff --git a/docs/source/exceptions/build_data_error.inc b/doc/source/exceptions/build_data_error.inc similarity index 90% rename from docs/source/exceptions/build_data_error.inc rename to doc/source/exceptions/build_data_error.inc index 3fcd3d29..1e98893b 100644 --- a/docs/source/exceptions/build_data_error.inc +++ b/doc/source/exceptions/build_data_error.inc @@ -18,7 +18,9 @@ BuildData Errors ---------------- -.. autoexception:: drydock_provisioner.error.BuildDataError +.. currentmodule:: drydock_provisioner.error + +.. autoexception:: BuildDataError :members: :show-inheritance: :undoc-members: diff --git a/docs/source/exceptions/client_error.inc b/doc/source/exceptions/client_error.inc similarity index 85% rename from docs/source/exceptions/client_error.inc rename to doc/source/exceptions/client_error.inc index 989143e0..2dc6fd51 100644 --- a/docs/source/exceptions/client_error.inc +++ b/doc/source/exceptions/client_error.inc @@ -17,12 +17,14 @@ Client Errors ------------- -.. autoexception:: drydock_provisioner.error.ClientForbiddenError +.. currentmodule:: drydock_provisioner.error + +.. autoexception:: ClientForbiddenError :members: :show-inheritance: :undoc-members: -.. autoexception:: drydock_provisioner.error.ClientUnauthorizedError +.. autoexception:: ClientUnauthorizedError :members: :show-inheritance: :undoc-members: diff --git a/docs/source/exceptions/design_error.inc b/doc/source/exceptions/design_error.inc similarity index 82% rename from docs/source/exceptions/design_error.inc rename to doc/source/exceptions/design_error.inc index 20c2048b..81d04eb1 100644 --- a/docs/source/exceptions/design_error.inc +++ b/doc/source/exceptions/design_error.inc @@ -17,17 +17,19 @@ Design Errors ------------- -.. autoexception:: drydock_provisioner.error.DesignError +.. currentmodule:: drydock_provisioner.error + +.. autoexception:: DesignError :members: :show-inheritance: :undoc-members: -.. autoexception:: drydock_provisioner.error.IngesterError +.. autoexception:: IngesterError :members: :show-inheritance: :undoc-members: -.. autoexception:: drydock_provisioner.error.InvalidDesignReference +.. autoexception:: InvalidDesignReference :members: :show-inheritance: :undoc-members: diff --git a/docs/source/exceptions/driver_error.inc b/doc/source/exceptions/driver_error.inc similarity index 75% rename from docs/source/exceptions/driver_error.inc rename to doc/source/exceptions/driver_error.inc index 82a49908..d6251421 100644 --- a/docs/source/exceptions/driver_error.inc +++ b/doc/source/exceptions/driver_error.inc @@ -17,27 +17,29 @@ Driver Errors ------------- -.. autoexception:: drydock_provisioner.error.DriverError +.. currentmodule:: drydock_provisioner.error + +.. autoexception:: DriverError :members: :show-inheritance: :undoc-members: -.. autoexception:: drydock_provisioner.error.InvalidSizeFormat +.. autoexception:: InvalidSizeFormat :members: :show-inheritance: :undoc-members: -.. autoexception:: drydock_provisioner.error.NotEnoughStorage +.. autoexception:: NotEnoughStorage :members: :show-inheritance: :undoc-members: -.. autoexception:: drydock_provisioner.error.PersistentDriverError +.. autoexception:: PersistentDriverError :members: :show-inheritance: :undoc-members: -.. autoexception:: drydock_provisioner.error.TransientDriverError +.. autoexception:: TransientDriverError :members: :show-inheritance: :undoc-members: diff --git a/docs/source/exceptions/exceptions.rst b/doc/source/exceptions/exceptions.rst similarity index 100% rename from docs/source/exceptions/exceptions.rst rename to doc/source/exceptions/exceptions.rst diff --git a/docs/source/exceptions/index.rst b/doc/source/exceptions/index.rst similarity index 100% rename from docs/source/exceptions/index.rst rename to doc/source/exceptions/index.rst diff --git a/docs/source/exceptions/orchestrator_error.inc b/doc/source/exceptions/orchestrator_error.inc similarity index 86% rename from docs/source/exceptions/orchestrator_error.inc rename to doc/source/exceptions/orchestrator_error.inc index 8120faf4..5abe3ef1 100644 --- a/docs/source/exceptions/orchestrator_error.inc +++ b/doc/source/exceptions/orchestrator_error.inc @@ -18,12 +18,14 @@ Orchestrator Errors ------------------- -.. autoexception:: drydock_provisioner.error.MaxRetriesReached +.. currentmodule:: drydock_provisioner.error + +.. autoexception:: MaxRetriesReached :members: :show-inheritance: :undoc-members: -.. autoexception:: drydock_provisioner.error.OrchestratorError +.. autoexception:: OrchestratorError :members: :show-inheritance: :undoc-members: diff --git a/docs/source/getting_started.rst b/doc/source/getting_started.rst similarity index 100% rename from docs/source/getting_started.rst rename to doc/source/getting_started.rst diff --git a/docs/source/images/architecture.png b/doc/source/images/architecture.png similarity index 100% rename from docs/source/images/architecture.png rename to doc/source/images/architecture.png diff --git a/docs/source/images/basic_task_sequence.png b/doc/source/images/basic_task_sequence.png similarity index 100% rename from docs/source/images/basic_task_sequence.png rename to doc/source/images/basic_task_sequence.png diff --git a/docs/source/index.rst b/doc/source/index.rst similarity index 95% rename from docs/source/index.rst rename to doc/source/index.rst index 9c36bb76..219a69f8 100644 --- a/docs/source/index.rst +++ b/doc/source/index.rst @@ -70,3 +70,11 @@ Topology Documentation topology troubleshooting/index + +Blueprints +---------- + +.. toctree:: + :maxdepth: 1 + + blueprints/index diff --git a/docs/source/policy-enforcement.rst b/doc/source/policy-enforcement.rst similarity index 100% rename from docs/source/policy-enforcement.rst rename to doc/source/policy-enforcement.rst diff --git a/docs/source/sampleconf.rst b/doc/source/sampleconf.rst similarity index 100% rename from docs/source/sampleconf.rst rename to doc/source/sampleconf.rst diff --git a/docs/source/task.rst b/doc/source/task.rst similarity index 100% rename from docs/source/task.rst rename to doc/source/task.rst diff --git a/docs/source/topology.rst b/doc/source/topology.rst similarity index 98% rename from docs/source/topology.rst rename to doc/source/topology.rst index 49ed7be0..dccc53e5 100644 --- a/docs/source/topology.rst +++ b/doc/source/topology.rst @@ -181,7 +181,7 @@ defined. * ``gateway``: The gateway IP on this Network to use for accessing the destination * ``metric``: The metric or weight for this route * ``routedomain``: Use this route's gateway and metric for accessing networks in the - defined routedomain. + defined routedomain. ``dns`` is used for specifying the list of DNS servers to use if this network is the primary network for the node. @@ -191,7 +191,7 @@ is the primary network for the node. addresses assigned from this Network DHCP Relay -~~~~~~~~~~ +^^^^^^^^^^ DHCP relaying is used when a DHCP server is not attached to the same layer 2 broadcast domain as nodes that are being PXE booted. The DHCP requests from the @@ -283,7 +283,7 @@ An example HardwareProfile document: count: 530000 Device Aliases -~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^ Device aliases are a way of mapping a particular device bus address to an alias. In the example above we map the PCI address ``0000:00:03.0`` @@ -294,7 +294,7 @@ at PCI address ``0000.00.03.0``. Currently device aliases are supported for network interface slave devices and storage physical devices. Kernel Parameter References -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^ Some kernel parameters specified in a host profile rely on particular hardware builds, such as ``isolcpus``. To support the greatest flexibility in building @@ -358,7 +358,7 @@ adopted from *defaults*) and can then again override or append any configuration that is specific to that node. Defining Node Out-Of-Band Management -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Drydock supports plugin-based OOB management. At a minimum a OOB driver supports configuring a node to PXE boot during the next @@ -370,7 +370,7 @@ parameters are required for that type and what capabilities are available via OOB driver tasks. IPMI -**** +"""" The ``ipmi`` OOB type requires additional configuration to allow OOB management: @@ -386,7 +386,7 @@ Currently the IPMI driver supports only basic management by setting nodes to PXE power-cycling the node. Libvirt -******* +""""""" The ``libvirt`` OOB type requires additional configuration within the site definition as well as particular configuration in the deployment of Drydock (and likely the node @@ -407,7 +407,7 @@ Currently the Libvirt driver supports only basic management by setting nodes to power-cycling the node. Defining Node Interfaces and Network Addressing -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Node network attachment can be described in a ``HostProfile`` or a ``BaremetalNode`` document. Node addressing is allowed only in a @@ -420,7 +420,7 @@ Once the interface attachments to networks is defined, ``HostProfile`` and which network the node should use as the primary route. Interfaces -********** +"""""""""" Interfaces for a node can be described in either a ``HostProfile`` or ``BaremetalNode`` definition. This will attach a defined NetworkLink to a host @@ -467,7 +467,7 @@ that interface for an inherited configuration. have trunking enabled or the design validation will fail. Addressing -********** +"""""""""" Addressing for a node can only be defined in a ``BaremetalNode`` definition. The ``addressing`` stanza simply defines a static IP address or ``dhcp`` for each @@ -492,7 +492,7 @@ Example ``addressing`` YAML schema: Defining Node Storage -~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^ Storage can be defined in the ``storage`` stanza of either a HostProfile or BaremetalNode document. The storage configuration can describe the creation of @@ -539,13 +539,13 @@ Example YAML schema of the ``storage`` stanza: mount_options: 'defaults' Schema -****** +"""""" The ``storage`` stanza can contain two top-level keys: ``physical_devices`` and ``volume_groups``. The latter is optional. Physical Devices and Partitions -******************************* +""""""""""""""""""""""""""""""" A physical device can either be carved up in partitions (including a single partition consuming the entire device) or added to a volume group as a physical @@ -563,7 +563,7 @@ mapping with the following keys volume. Incompatible with the ``partitions`` specification. Partition -^^^^^^^^^ +""""""""" A partition mapping describes a GPT partition on a physical disk. It can be left as a raw block device or formatted and mounted as a filesystem. @@ -585,7 +585,7 @@ as a raw block device or formatted and mounted as a filesystem. * ``fs_label``: A filesystem label to assign to the filesystem. Optional. Size Format -^^^^^^^^^^^ +""""""""""" The size specification for a partition or logical volume is formed from three parts: @@ -602,7 +602,7 @@ parts: * %: The percentage of total device or volume group space Volume Groups and Logical Volumes -********************************* +""""""""""""""""""""""""""""""""" Logical volumes can be used to create RAID-0 volumes spanning multiple physical disks or partitions. Each key in the ``volume_groups`` mapping is a name @@ -616,7 +616,7 @@ invalid. Each mapping value is another mapping describing the volume group. created in the volume group Logical Volume -^^^^^^^^^^^^^^ +"""""""""""""" A logical volume is a RAID-0 volume. Using logical volumes for ``/`` and ``/boot`` is supported @@ -637,7 +637,7 @@ and ``kernel`` to use as well as customize the kernel configuration with ``kernel_params``. Image and Kernel Selection -************************** +^^^^^^^^^^^^^^^^^^^^^^^^^^ The valid ``image`` and ``kernel`` values are dependent on what is supported by your node provisioner. In the example of Canonical MaaS using the 16.04 LTS @@ -645,7 +645,7 @@ image, the values would be ``image: 'xenial'`` and ``kernel: 'ga-16.04'`` for th LTS kernel or ``kernel: hwe-16.04`` for the hardware-enablement kernel. Kernel Parameters -***************** +^^^^^^^^^^^^^^^^^ The ``kernel_params`` configuration is a mapping. Each key should either be a string or boolean value. For boolean ``true`` values, the key will be added to the kernel @@ -653,7 +653,7 @@ parameter list as a flag. For string values, the key:value pair will be added to kernel parameter list as ``key=value``. Parameter References -^^^^^^^^^^^^^^^^^^^^ +"""""""""""""""""""" One special case is supported for values that match a hardware profile reference. When the parameter is rendered for a particular node, the value included in the diff --git a/docs/source/troubleshooting/index.rst b/doc/source/troubleshooting/index.rst similarity index 100% rename from docs/source/troubleshooting/index.rst rename to doc/source/troubleshooting/index.rst diff --git a/docs/source/troubleshooting/validations.rst b/doc/source/troubleshooting/validations.rst similarity index 83% rename from docs/source/troubleshooting/validations.rst rename to doc/source/troubleshooting/validations.rst index 542882bc..2337a34c 100644 --- a/docs/source/troubleshooting/validations.rst +++ b/doc/source/troubleshooting/validations.rst @@ -14,17 +14,17 @@ License for the specific language governing permissions and limitations under the License. -============================= -Dryodck Topology Validation -============================= +=========================== +Drydock Topology Validation +=========================== DD1XXX - Storage Validations -============================= +============================ To be continued DD2XXX - Network Validations -============================= +============================ To be continued @@ -34,6 +34,6 @@ DD3XXX - Platform Validations To be continued DD4XXX - Bootaction Validations -============================= +=============================== To be continued diff --git a/docs/source/validatedesign.rst b/doc/source/validatedesign.rst similarity index 88% rename from docs/source/validatedesign.rst rename to doc/source/validatedesign.rst index 9d128b92..506d3596 100644 --- a/docs/source/validatedesign.rst +++ b/doc/source/validatedesign.rst @@ -27,5 +27,7 @@ Validation Checks These checks are meant to check the business logic of documents sent to the validatedesign API. -.. autoclass:: drydock_provisioner.orchestrator.validations.validator.Validator +.. currentmodule:: drydock_provisioner.orchestrator.validations.validator + +.. autoclass:: Validator :members: diff --git a/images/drydock/Dockerfile b/images/drydock/Dockerfile index 50e1eabf..1ef8730a 100644 --- a/images/drydock/Dockerfile +++ b/images/drydock/Dockerfile @@ -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 diff --git a/tools/gate/playbooks/doc-publish.yaml b/tools/gate/playbooks/doc-publish.yaml deleted file mode 100644 index b444ac55..00000000 --- a/tools/gate/playbooks/doc-publish.yaml +++ /dev/null @@ -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 diff --git a/tools/gate/playbooks/omni_test.yaml b/tools/gate/playbooks/omni_test.yaml index a5a03a2f..d62be2e0 100644 --- a/tools/gate/playbooks/omni_test.yaml +++ b/tools/gate/playbooks/omni_test.yaml @@ -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 }}" diff --git a/tox.ini b/tox.ini index c54775a7..f90594b5 100644 --- a/tox.ini +++ b/tox.ini @@ -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