DEVAI-196: Helm Chart README and JSON Schema generation

.github/workflows/lint.yaml

@@ -0,0 +1,52 @@
+name: Lint Charts
+
+on:
+  pull_request:
+    paths:
+      - "charts/**"
+
+jobs:
+  check-readme:
+    runs-on: ubuntu-latest
+    env:
+      GO111MODULE: on
+    steps:
+      - name: Checkout
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # pin@v3
+
+      - uses: actions/setup-python@0b93645e9fea7318ecaed2b359559ac225c90a2b # pin@v4
+        with:
+          python-version: 3.12
+
+      - uses: actions/setup-go@41dfa10bad2bb2ae585af6ee5bb4d7d973ad74ed # pin@v3
+        with:
+          go-version: ^1
+
+      - name: Setup helm-docs
+        run: go install github.com/norwoodj/helm-docs/cmd/helm-docs@latest
+
+      - name: Run pre-commit
+        uses: pre-commit/action@2c7b3805fd2a0fd8c1884dcaebf91fc102a13ecd # [email protected]
+        with:
+          extra_args: helm-docs --all-files
+
+  check-jsonschema-dereference:
+    runs-on: ubuntu-latest
+    env:
+      GO111MODULE: on
+    steps:
+      - name: Checkout
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # pin@v3
+
+      - uses: actions/setup-python@0b93645e9fea7318ecaed2b359559ac225c90a2b # pin@v4
+        with:
+          python-version: 3.12
+
+      - uses: actions/setup-go@41dfa10bad2bb2ae585af6ee5bb4d7d973ad74ed # pin@v3
+        with:
+          go-version: ^1
+
+      - name: Run pre-commit
+        uses: pre-commit/action@2c7b3805fd2a0fd8c1884dcaebf91fc102a13ecd
+        with:
+            extra_args: jsonschema-dereference --all-files

.gitignore

@@ -1,2 +1,3 @@
 private-values.yaml
 *~
+env

.pre-commit-config.yaml

@@ -0,0 +1,20 @@
+repos:
+  - repo: https://github.com/norwoodj/helm-docs
+    rev: v1.2.0
+    hooks:
+      - id: helm-docs
+        args:
+          # Make the tool search for charts only under the ``charts` directory
+          - --chart-search-root=charts
+          # The `./` makes it relative to the chart-search-root set above
+          - --template-files=./_templates.gotmpl
+          # A base filename makes it relative to each chart directory found
+          - --template-files=README.md.gotmpl
+  - repo: local
+    hooks:
+      - id: jsonschema-dereference
+        name: jsonschema-dereference
+        entry: python .pre-commit/jsonschema_dereference.py
+        additional_dependencies: [jsonref]
+        language: python
+        types_or: [yaml, json]

.pre-commit/jsonschema_dereference.py

@@ -0,0 +1,54 @@
+""" 
+This Python module:
+  - Searches for JSON Schema templates with the name values.schema.tmpl.json
+  - Dereferences any $refs contained in those files
+  - Outputs the new Schema to a values.schema.json file in the same directory
+"""
+
+import sys
+import json
+from typing import List, Dict, Any
+from pathlib import Path
+
+# External library dependency
+# Install with 'pip install jsonref'
+import jsonref
+
+# File to write the dereferenced JSON Schema to
+JSONSCHEMA_NAME = "values.schema.json"
+# File that contains the JSON Schema that needs dereferencing
+JSONSCHEMA_TEMPLATE_NAME = "values.schema.tmpl.json"
+
+def load_template_schema(schema_dir: Path) -> Dict[str, Any]:
+    """Load the schema template values.schema.tmpl.json"""
+    with open(schema_dir / JSONSCHEMA_TEMPLATE_NAME, "r", encoding="utf-8") as f:
+        return json.loads(f.read())
+
+def save(schema_dir: Path, schema_data: Any) -> None:
+    """Save the dereferenced schema to values.schema.json"""
+    with open(schema_dir / JSONSCHEMA_NAME, "w", encoding="utf-8") as f:
+        json.dump(schema_data, f, indent=4, sort_keys=True)
+
+if __name__ == '__main__':
+    # Search for all values.schema.tmpl.json files
+    schema_templates = [p.parent for p in Path(".").rglob(JSONSCHEMA_TEMPLATE_NAME)]
+
+    # Create a list to hold any exceptions
+    errors: List[BaseException] = []
+    # Iterate over the List of found schema templates
+    for schema_template in schema_templates:
+        try:
+            # Load the schema into a variable as JSON
+            st = load_template_schema(schema_template)
+            # Dereference all of the $refs
+            s = jsonref.replace_refs(st)
+            # Save the dereferenced JSON
+            save(schema_template, s)
+        except BaseException as e:
+            # Print any errors to the screen
+            print(f"Could not process schema for '{schema_template}': {e}")
+            # Append any exceptions to the errors List
+            errors.append(e)
+    if errors:
+        # Exit with status 1 if any exceptions were thrown
+        sys.exit(1)

CONTRIBUTING.md

@@ -0,0 +1,32 @@
+# Contributing
+
+## External Tools
+
+You will need to have the following tools installed to generate README and JSON Schema files from their respective templates.
+
+### Pre-Commit
+
+Once this tool is installed you will need to run the `make install-pre-commit` to install the git pre-commit hook so that it will run and render the templates before you commit and push the changes in your pull request.
+
+#### Description
+
+Git hook scripts are useful for identifying simple issues before submission to code review. We run our hooks on every commit to automatically point out issues in code such as missing semicolons, trailing whitespace, and debug statements. By pointing these issues out before code review, this allows a code reviewer to focus on the architecture of a change while not wasting time with trivial style nitpicks.
+
+#### Links
+
+Website: [pre-commit.com](http://pre-commit.com/)  
+Documentation: [pre-commit.com](http://pre-commit.com/)  
+Example(s): [.pre-commit-config.yaml](https://github.com/backstage/charts/blob/main/.pre-commit-config.yaml)
+
+### Helm-Docs
+
+#### Description
+
+The helm-docs tool auto-generates documentation from helm charts into markdown files. The resulting files contain metadata about their respective chart and a table with each of the chart's values, their defaults, and an optional description parsed from comments.
+The markdown generation is entirely Go template driven. The tool parses metadata from charts and generates a number of sub-templates that can be referenced in a template file (by default README.md.gotmpl). If no template file is provided, the tool has a default internal template that will generate a reasonably formatted README.
+
+#### Links
+
+Repository: [norwoodj/helm-docs](https://github.com/norwoodj/helm-docs)  
+Documentation: [README.md](https://github.com/norwoodj/helm-docs/blob/master/README.md)  
+Example(s): [pre-commit-hook](https://github.com/backstage/charts/blob/main/.pre-commit-config.yaml#L2-L12)

Makefile

@@ -0,0 +1,36 @@
+##@ Generation
+
+.PHONY: generate
+generate: ## Run all generation commands
+	pre-commit run --all-files
+
+.PHONY: helm-docs
+helm-docs: ## Generate README.md from the README.md.gotmpl file
+	pre-commit run helm-docs --all-files
+
+.PHONY: jsonschema-dereference
+jsonschema-dereference: ## Generate values.schema.json from the values.schema.tmpl.json file
+	pre-commit run jsonschema-dereference --all-files
+
+##@ Scripts	
+
+.PHONY: install-pre-commit
+install-pre-commit: ## Install the pre-commit script
+	pre-commit install
+
+##@ General
+
+# The help target prints out all targets with their descriptions organized
+# beneath their categories. The categories are represented by '##@' and the
+# target descriptions by '##'. The awk command is responsible for reading the
+# entire set of makefiles included in this invocation, looking for lines of the
+# file as xyz: ## something, and then pretty-format the target and help. Then,
+# if there's a line with ##@ something, that gets pretty-printed as a category.
+# More info on the usage of ANSI control characters for terminal formatting:
+# https://en.wikipedia.org/wiki/ANSI_escape_code#SGR_parameters
+# More info on the awk command:
+# http://linuxcommand.org/lc3_adv_awk.php
+
+.PHONY: help
+help: ## Display this help.
+	@awk 'BEGIN {FS = ":.*##"; printf "\nUsage:\n  make \033[36m<target>\033[0m\n"} /^[a-zA-Z_0-9-]+:.*?##/ { printf "  \033[36m%-15s\033[0m %s\n", $$1, $$2 } /^##@/ { printf "\n\033[1m%s\033[0m\n", substr($$0, 5) } ' $(MAKEFILE_LIST)

charts/_templates.gotmpl

@@ -0,0 +1,7 @@
+{{ define "chart.valuesTable" }}
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+{{- range .Values }}
+| {{ .Key }} | {{ .Type }} | {{ if .Default }}{{ .Default }}{{ else }}{{ .AutoDefault }}{{ end }} | {{ if .Description }}{{ .Description }}{{ else }}{{ .AutoDescription }}{{ end }} |
+{{- end }}
+{{ end }}

charts/ai-software-templates/chatbot/Chart.yaml

@@ -1,8 +1,37 @@
+# The chart API version (required)
 apiVersion: v2
+# The name of the chart (required)
+name: chatbot-ai-sample
+# A SemVer 2 version (required)
+version: 0.1.1
+# A SemVer range of compatible Kubernetes versions (optional)
 kubeVersion: ">= 1.27.0-0"
+# A single-sentence description of this project (optional)
+description: This Helm Chart deploys a Large Language Model (LLM)-enabled [chat bot application](https://github.com/redhat-ai-dev/ai-lab-samples/tree/main/chatbot).
+# The type of the chart (optional)
+type: application
+# A list of keywords about this project (optional)
+keywords:
+  - chatbot
+  - llama.cpp
+  - ai-lab 
+# The URL of this projects home page (optional)
+home: https://github.com/redhat-ai-dev/ai-lab-helm-charts
+# A list of URLs to source code for this project (optional)
+sources:
+  - https://github.com/redhat-ai-dev/ai-lab-template
+# A list of the chart requirements (optional)
+dependencies: []
+# A list of maintainers of this project (optional)
+maintainers:
+  - name: Red Hat AI Development Team
+    url: https://github.com/redhat-ai-dev
+# A URL to an SVG or PNG image to be used as an icon (optional)
+# icon: ""
+# The version of the app that this contains (optional). Needn't be SemVer. Quotes recommended.
+# appVersion: 
+# Whether this chart is deprecated (optional, boolean)
+deprecated: false
+# A list of annotations keyed by name (optional)
 annotations:
   charts.openshift.io/name: Chatbot AI Sample
-description: A Helm chart for the Chatbot AI Sample app. For more information please check https://github.com/redhat-ai-dev/ai-lab-helm-charts.git
-name: chatbot-ai-sample
-tags: chatbot,llama.cpp,ai-lab
-version: 0.1.1