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>
This commit is contained in:
Doug Goldstein 2024-11-11 16:49:14 -06:00
parent 9f633d05b7
commit 178c777c1e
No known key found for this signature in database
9 changed files with 192 additions and 3 deletions

5
.gitignore vendored
View File

@ -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

View File

@ -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

41
doc/helm-docs.rst.gotmpl Normal file
View File

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

View File

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

View File

@ -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

6
doc/source/conf.py Executable file → Normal file
View File

@ -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

View File

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

View File

@ -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

View File

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