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 <cardoe@cardoe.com>

.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

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
+CHART_DIRS := $(subst /,,$(dir $(wildcard */Chart.yaml)))
-CHARTS := helm-toolkit $(filter-out $(EXCLUDES), $(patsubst %/.,%,$(wildcard */.)))
+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

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" . }}

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,
+    }

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

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

doc/source/index.rst

@@ -8,6 +8,7 @@ Contents:
 
     readme
     install/index
+    chart/index
     devref/index
     testing/index
     troubleshooting/index

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
 

zuul.d/base.yaml

@@ -39,6 +39,7 @@
       - openstack/openstack-helm-plugin
     irrelevant-files:
       - ^.*\.rst$
+      - ^.*\.rst.gotmpl$
       - ^doc/.*$
       - ^releasenotes/.*$
     timeout: 7200