From 178c777c1ed935c167bbe5a62f61b589123d6d0a Mon Sep 17 00:00:00 2001 From: Doug Goldstein Date: Mon, 11 Nov 2024 16:49:14 -0600 Subject: [PATCH] use helm-docs to generate docs for the values.yaml For each chart, generate configuration docs for the values.yaml Install helm-docs into the tools directory since it's not available via distro packages. Change-Id: Icffec6637686871d10aba2f666075549d1d505a8 Signed-off-by: Doug Goldstein --- .gitignore | 5 +++ Makefile | 20 +++++++-- doc/helm-docs.rst.gotmpl | 41 +++++++++++++++++ doc/source/_exts/helm_docs.py | 85 +++++++++++++++++++++++++++++++++++ doc/source/chart/index.rst | 33 ++++++++++++++ doc/source/conf.py | 6 +++ doc/source/index.rst | 1 + tox.ini | 3 ++ zuul.d/base.yaml | 1 + 9 files changed, 192 insertions(+), 3 deletions(-) create mode 100644 doc/helm-docs.rst.gotmpl create mode 100644 doc/source/_exts/helm_docs.py create mode 100644 doc/source/chart/index.rst mode change 100755 => 100644 doc/source/conf.py diff --git a/.gitignore b/.gitignore index fc5c6db5f5..0973341dbe 100644 --- a/.gitignore +++ b/.gitignore @@ -43,6 +43,11 @@ output/*/index.html # Sphinx doc/build +doc/source/chart/* +!doc/source/chart/index.rst + +# installed tools +tools/helm-docs # pbr generates these AUTHORS diff --git a/Makefile b/Makefile index ca559bdf84..d2be66bcaf 100644 --- a/Makefile +++ b/Makefile @@ -14,6 +14,9 @@ SHELL := /bin/bash HELM := helm TASK := build +HELM_DOCS := tools/helm-docs +UNAME_OS := $(shell uname -s) +UNAME_ARCH := $(shell uname -m) PKG_ARGS = ifdef VERSION @@ -24,10 +27,10 @@ ifdef PACKAGE_DIR PKG_ARGS += --destination $(PACKAGE_DIR) endif -EXCLUDES := helm-toolkit doc tests tools logs tmp zuul.d releasenotes roles -CHARTS := helm-toolkit $(filter-out $(EXCLUDES), $(patsubst %/.,%,$(wildcard */.))) +CHART_DIRS := $(subst /,,$(dir $(wildcard */Chart.yaml))) +CHARTS := $(sort helm-toolkit $(CHART_DIRS)) -.PHONY: $(EXCLUDES) $(CHARTS) +.PHONY: $(CHARTS) all: $(CHARTS) @@ -38,6 +41,17 @@ $(CHARTS): make $(TASK)-$@; \ fi +HELM_DOCS_VERSION ?= 1.14.2 +.PHONY: helm-docs ## Download helm-docs locally if necessary +helm-docs: $(HELM_DOCS) +$(HELM_DOCS): + { \ + curl -fsSL -o tools/helm-docs.tar.gz https://github.com/norwoodj/helm-docs/releases/download/v$(HELM_DOCS_VERSION)/helm-docs_$(HELM_DOCS_VERSION)_$(UNAME_OS)_$(UNAME_ARCH).tar.gz && \ + tar -zxf tools/helm-docs.tar.gz -C tools helm-docs && \ + rm -f tools/helm-docs.tar.gz && \ + chmod +x tools/helm-docs; \ + } + init-%: if [ -f $*/Makefile ]; then make -C $*; fi if [ -f $*/requirements.yaml ]; then $(HELM) dep up $*; fi diff --git a/doc/helm-docs.rst.gotmpl b/doc/helm-docs.rst.gotmpl new file mode 100644 index 0000000000..002fcadeac --- /dev/null +++ b/doc/helm-docs.rst.gotmpl @@ -0,0 +1,41 @@ +{{- define "chart.valueDefaultColumnRender" }} +{{- $defaultValue := (default .Default .AutoDefault) -}} +{{- $notationType := .NotationType }} +{{- if (and (hasPrefix "```" $defaultValue) (hasSuffix "```" $defaultValue) ) -}} +{{- $defaultValue = (toPrettyJson (fromJson (trimAll "```" (default .Default .AutoDefault) ) ) ) -}} +{{- $notationType = "json" }} +{{- end -}} +{{- if contains "\\n" $defaultValue }} +{{- $notationType = "default" }} +{{- end }} +{{- if eq $notationType "" -}} +{{ $defaultValue }} +{{- else -}} +.. code-block:: {{ $notationType }} + +{{ (trimAll "`" $defaultValue | trimAll "\"" | replace "\\n" "\n") | indent 10 }} +{{- end }} +{{- end }} + +{{ title .Name }} +{{ repeat (len .Name) "=" }} + +There are various customizations you can do to tailor the deployment of +OpenStack {{ title .Name }}. You can find those below. + +================== +General Parameters +================== + + {{- define "chart.generalParamsvaluesTable" }} + {{- range .Values }} + * {{ .Key }} + + * Type: {{ .Type }} + * Description: {{ if .Description }}{{ .Description }}{{ else }}{{ .AutoDescription }}{{ end }} + * {{ template "chart.valueDefaultColumnRender" . }} + + {{- end }} + {{- end }} + + {{ template "chart.generalParamsvaluesTable" . }} diff --git a/doc/source/_exts/helm_docs.py b/doc/source/_exts/helm_docs.py new file mode 100644 index 0000000000..2e0cdce50a --- /dev/null +++ b/doc/source/_exts/helm_docs.py @@ -0,0 +1,85 @@ +# All Rights Reserved. +# +# 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. + +from pathlib import Path +import subprocess +from sphinx.application import Sphinx +from sphinx.util import logging +from sphinx.util.typing import ExtensionMetadata + +PREFIX = "[helm_docs] " +VERSION = "0.1" + +# the main template we use for all charts +HELMDOCSTMPL = "helm-docs.rst.gotmpl" +LOCALHELMDOCSTMPL = "README.rst.gotmpl" + + +logger = logging.getLogger(__name__) + + +def _run_helm_docs( + helmdocsbin: Path, + rootdir: Path, + outfile: Path, + chart: str, + helmdocstmpl: Path, + charttmpl: Path | None, +): + tmpls = [str(p) for p in [helmdocstmpl, charttmpl] if p is not None] + cmd = [ + str(helmdocsbin), + "--output-file", + str(outfile), + "--template-files", + ",".join(tmpls), + "--chart-search-root", + chart, + ] + subprocess.run(cmd, cwd=str(rootdir), check=True) + + +def setup(app: Sphinx) -> ExtensionMetadata: + logger.info(PREFIX + "plugin %s", VERSION) + + # calculate our repo root level + rootdir = (Path(app.srcdir) / ".." / "..").resolve() + # our helm-docs binary + helmdocsbin = rootdir / "tools" / "helm-docs" + # this is where we will be writing our docs which + # must be a relative path from a chart directory + outdir = Path("..") / "doc" / "source" / "chart" + # where our main helm template is which must be + # relative to a chart directory + helmdocstmpl = Path("..") / "doc" / HELMDOCSTMPL + + # find each chart + for chartyaml in rootdir.rglob("Chart.yaml"): + # the directory to the chart + chartdir = chartyaml.parent + # name of our chart + chart = chartyaml.parent.name + logger.info(PREFIX + "found %s", chart) + # does the chart have a local template to include + localtmpl = ( + LOCALHELMDOCSTMPL if (chartdir / "README.rst.gotmpl").exists() else None + ) + outfile = outdir / f"{chart}.rst" + _run_helm_docs(helmdocsbin, rootdir, outfile, chart, helmdocstmpl, localtmpl) + + return { + "version": VERSION, + "parallel_read_safe": True, + "parallel_write_safe": True, + } diff --git a/doc/source/chart/index.rst b/doc/source/chart/index.rst new file mode 100644 index 0000000000..7a55d4aa71 --- /dev/null +++ b/doc/source/chart/index.rst @@ -0,0 +1,33 @@ +Chart Options +============= + +Here are the charts with their documented values.yaml's for OpenStack Helm: + +.. toctree:: + :maxdepth: 2 + + aodh + barbican + ceilometer + cinder + cyborg + designate + glance + heat + horizon + ironic + keystone + magnum + manila + masakari + mistral + monasca + neutron + nova + octavia + openstack + placement + rally + senlin + tacker + tempest diff --git a/doc/source/conf.py b/doc/source/conf.py old mode 100755 new mode 100644 index 19fe28d9d9..601bf755c0 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -14,6 +14,11 @@ import os import sys +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +sys.path.insert(0, os.path.join(os.path.abspath('.'), '_exts')) + sys.path.insert(0, os.path.abspath('../..')) # -- General configuration ---------------------------------------------------- @@ -21,6 +26,7 @@ sys.path.insert(0, os.path.abspath('../..')) # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones. extensions = [ 'openstackdocstheme', + 'helm_docs', ] # openstackdocstheme options diff --git a/doc/source/index.rst b/doc/source/index.rst index 3d819a169e..aa671e3e63 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -8,6 +8,7 @@ Contents: readme install/index + chart/index devref/index testing/index troubleshooting/index diff --git a/tox.ini b/tox.ini index d1f0373649..13b3b6a19e 100644 --- a/tox.ini +++ b/tox.ini @@ -19,8 +19,10 @@ deps = -r{toxinidir}/doc/requirements.txt commands = rm -rf doc/build + make helm-docs sphinx-build -W --keep-going -b html -j auto doc/source doc/build/html allowlist_externals = + make rm [testenv:pdf-docs] @@ -31,6 +33,7 @@ allowlist_externals = rm commands = rm -rf doc/build/pdf + make helm-docs sphinx-build -W --keep-going -b latex -j auto doc/source doc/build/pdf make -C doc/build/pdf diff --git a/zuul.d/base.yaml b/zuul.d/base.yaml index ea95910de3..b2c9eaa31a 100644 --- a/zuul.d/base.yaml +++ b/zuul.d/base.yaml @@ -39,6 +39,7 @@ - openstack/openstack-helm-plugin irrelevant-files: - ^.*\.rst$ + - ^.*\.rst.gotmpl$ - ^doc/.*$ - ^releasenotes/.*$ timeout: 7200