docs: update HtmlTest and API docs generator for new docs page (keptn…

…#2651)

Signed-off-by: Arya Soni <[email protected]>

.github/actions/spelling/expect.txt

@@ -119,6 +119,7 @@ cyclomatic
 cytopia
 daemonset
 dario
+databranch
 datadog
 datasource
 datetime
@@ -198,6 +199,8 @@ getjson
 getopt
 gexec
 gha
+ghrs
+ghtoken
 ginkgotypes
 Gitlab
 gke
@@ -217,6 +220,7 @@ govulncheck
 grafana
 graphql
 groupversion
+gstatic
 gtag
 GVK
 haspopup
@@ -270,6 +274,7 @@ ITracer
 jaegertracing
 javascript
 jetstack
+jgehrcke
 Jhb
 jsonschema
 jwt
@@ -496,6 +501,7 @@ prebuilt
 Predeployment
 PREDEPLOYMENTEVALUATIONSTATUS
 PREDEPLOYMENTSTATUS
+prepost
 prepostdeployment
 prepostevaluation
 previewer
@@ -685,8 +691,3 @@ yml
 YOURNAME
 yourregistry
 youtube
-squidfunk
-databranch
-ghtoken
-jgehrcke
-ghrs

.github/scripts/generate-crd-docs/crd-docs-generator-config-lifecycle-v1alpha4.yaml

@@ -7,10 +7,10 @@ render:
   knownTypes:
     - name: ResourceReference
       package: github.com/keptn/lifecycle-toolkit/lifecycle-operator/apis/lifecycle/v1alpha3
-      link: ../v1alpha3/#resourcereference
+      link: ../v1alpha3/index.md#resourcereference
     - name: ItemStatus
       package: github.com/keptn/lifecycle-toolkit/lifecycle-operator/apis/lifecycle/v1alpha3
-      link: ../v1alpha3/#itemstatus
+      link: ../v1alpha3/index.md#itemstatus
     - name: Quantity
       package: "k8s.io/apimachinery/pkg/api/resource"
       link: https://pkg.go.dev/k8s.io/apimachinery/pkg/api/resource#Quantity

.github/scripts/generate-crd-docs/generate-crd-docs.sh

@@ -17,7 +17,7 @@ RENDERER='markdown'
 RENDERER_CONFIG_FILE_TEMPLATE_PATH='.github/scripts/generate-crd-docs/crd-docs-generator-config'
 RENDERER_CONFIG_FILE=$RENDERER_CONFIG_FILE_TEMPLATE_PATH'.yaml'
 PATH=$PATH:$(go env GOPATH)/bin
-DOCS_PATH=./docs/content/en/docs/reference/api-reference/
+DOCS_PATH=./docs-new/docs/reference/api-reference/
 
 echo "Checking if code generator tool is installed..."
 if ! test -s crd-ref-docs; then
@@ -32,14 +32,15 @@ echo "Running CRD docs auto-generator..."
 for api_group in "$OPERATOR_API_ROOT"*; do
 
   sanitized_api_group="${api_group#$OPERATOR_API_ROOT}"
-  INDEX_PATH="$DOCS_PATH$sanitized_api_group/_index.md"
+  INDEX_PATH="$DOCS_PATH$sanitized_api_group"
 
-  if [ ! -f "$INDEX_PATH" ]; then
+  if [ ! -f "$INDEX_PATH/index.md" ]; then
     echo "API group index file doesn't exist for group $sanitized_api_group. Creating it now..."
     # Use sanitized_api_group and make first char uppercase
     API_GROUP="$(tr '[:lower:]' '[:upper:]' <<< "${sanitized_api_group:0:1}")${sanitized_api_group:1}"
     export API_GROUP
-    envsubst < './.github/scripts/generate-crd-docs/templates/index-template.md' > "$INDEX_PATH"
+    mkdir -p "$INDEX_PATH"
+    envsubst < './.github/scripts/generate-crd-docs/templates/index-template.md' > "$INDEX_PATH/index.md"
     unset API_GROUP
   fi
   for api_version in "$api_group"/*; do
@@ -49,17 +50,21 @@ for api_group in "$OPERATOR_API_ROOT"*; do
 
     renderer_config_file="$RENDERER_CONFIG_FILE_TEMPLATE_PATH-$sanitized_api_group-$sanitized_api_version.yaml"
     if [ ! -f "$renderer_config_file" ]; then
+      echo "Using default configuration..."
       renderer_config_file=$RENDERER_CONFIG_FILE
+    else
+      echo "Using API version specific configuration..."
     fi
 
+
     echo "Arguments:"
     echo "TEMPLATE_DIR: $TEMPLATE_DIR"
     echo "OPERATOR_API_ROOT: $OPERATOR_API_ROOT"
     echo "API_GROUP: $sanitized_api_group"
     echo "API_VERSION: $sanitized_api_version"
     echo "RENDERER: $RENDERER"
     echo "RENDERER_CONFIG_FILE: $renderer_config_file"
-    echo "OUTPUT_PATH: $OUTPUT_PATH/_index.md"
+    echo "OUTPUT_PATH: $OUTPUT_PATH/index.md"
 
     echo "Creating docs folder $OUTPUT_PATH..."
     mkdir -p "$OUTPUT_PATH"
@@ -72,7 +77,7 @@ for api_group in "$OPERATOR_API_ROOT"*; do
       --renderer="$RENDERER" \
       --config "$renderer_config_file" \
       --max-depth 15 \
-      --output-path "$OUTPUT_PATH/_index.md"
+      --output-path "$OUTPUT_PATH/index.md"
     echo "---------------------"
   done
 done
@@ -81,14 +86,15 @@ done
 
 
 sanitized_api_group="metrics"
-INDEX_PATH="$DOCS_PATH$sanitized_api_group/_index.md"
+INDEX_PATH="$DOCS_PATH$sanitized_api_group"
 
-if [ ! -f "$INDEX_PATH" ]; then
+if [ ! -f "$INDEX_PATH/index.md" ]; then
   echo "API group index file doesn't exist for group $sanitized_api_group. Creating it now..."
   # Use sanitized_api_group and make first char uppercase
   API_GROUP="$(tr '[:lower:]' '[:upper:]' <<< "${sanitized_api_group:0:1}")${sanitized_api_group:1}"
   export API_GROUP
-  envsubst < './.github/scripts/generate-crd-docs/templates/index-template.md' > "$INDEX_PATH"
+  mkdir -p "$INDEX_PATH"
+  envsubst < './.github/scripts/generate-crd-docs/templates/index-template.md' > "$INDEX_PATH/index.md"
   unset API_GROUP
 fi
 
@@ -103,7 +109,7 @@ for api_version in "$METRICS_API_ROOT"*; do
   echo "API_VERSION: $sanitized_api_version"
   echo "RENDERER: $RENDERER"
   echo "RENDERER_CONFIG_FILE: $RENDERER_CONFIG_FILE"
-  echo "OUTPUT_PATH: $OUTPUT_PATH/_index.md"
+  echo "OUTPUT_PATH: $OUTPUT_PATH/index.md"
 
   echo "Creating docs folder $OUTPUT_PATH..."
   mkdir -p "$OUTPUT_PATH"
@@ -116,6 +122,6 @@ for api_version in "$METRICS_API_ROOT"*; do
     --renderer="$RENDERER" \
     --config "$RENDERER_CONFIG_FILE" \
     --max-depth 15 \
-    --output-path "$OUTPUT_PATH/_index.md"
+    --output-path "$OUTPUT_PATH/index.md"
   echo "---------------------"
 done

.github/scripts/generate-crd-docs/templates/gv_list.tpl

@@ -2,10 +2,10 @@
 {{- $groupVersions := . -}}
 {{- $groupVersion := index $groupVersions 0 -}}
 
----
-title: {{ $groupVersion.Version }}
-description: Reference information for {{ $groupVersion.GroupVersionString }}
----
+# {{ $groupVersion.Version }}
+
+Reference information for {{ $groupVersion.GroupVersionString }}
+
 <!-- markdownlint-disable -->
 
 ## Packages

.github/scripts/generate-crd-docs/templates/index-template.md

@@ -1,4 +1,3 @@
----
-title: $API_GROUP API
-description: Reference information about the $API_GROUP API
----
+# $API_GROUP API
+
+Reference information about the $API_GROUP API.

.github/workflows/htmltest.yaml

@@ -27,12 +27,14 @@ jobs:
       - uses: actions/checkout@v4
         with:
           submodules: true
+          fetch-depth: 0
 
       - name: Cache HTMLTest packages
         uses: actions/cache@v3
         with:
           path: |
             docs/tmp/.htmltest
+            tmp/.htmltest
           key: ${{ runner.os }}-htmltest
 
       - name: Cache Hugo packages

.gitignore

@@ -1,6 +1,7 @@
 bin/
 site/
 .cache/
+tmp/
 
 # Binaries for programs and plugins
 *.exe

Makefile

@@ -4,10 +4,6 @@
 KUSTOMIZE_VERSION?=v5.3.0
 CHART_APPVERSION ?= v0.9.0 # x-release-please-version
 
-# renovate: datasource=docker depName=squidfunk/mkdocs-material
-MKDOCS_DOCKER_IMAGE_VERSION=9.5.1
-MKDOCS_DOCKER_IMAGE=squidfunk/mkdocs-material
-
 # renovate: datasource=docker depName=cytopia/yamllint
 YAMLLINT_VERSION ?= alpine
 
@@ -138,30 +134,7 @@ build-deploy-certmanager:
 .PHONY: build-deploy-dev-environment
 build-deploy-dev-environment: build-deploy-certmanager build-deploy-operator build-deploy-metrics-operator build-deploy-scheduler
 
-include docs/Makefile
-
-PWD=$(shell pwd)
-
-.PHONY: docs-build
-docs-build:
-	docker run --rm -it -v ${PWD}/docs-new:/docs-new \
-		-v ${PWD}/mkdocs.yml:/mkdocs.yml \
-		-v ${PWD}/requirements.txt:/requirements.txt \
-		-v ${PWD}/.git:/.git \
-		--entrypoint "" \
-		${MKDOCS_DOCKER_IMAGE}:${MKDOCS_DOCKER_IMAGE_VERSION} \
-		sh -c 'cd /; pip install -r requirements.txt -q; mkdocs build'
-
-.PHONY: docs-serve
-docs-serve:
-	docker run --rm -it -p 8000:8000 \
-		-v ${PWD}/docs-new:/docs-new \
-		-v ${PWD}/mkdocs.yml:/mkdocs.yml \
-		-v ${PWD}/requirements.txt:/requirements.txt \
-		-v ${PWD}/.git:/.git \
-		--entrypoint "" \
-		${MKDOCS_DOCKER_IMAGE}:${MKDOCS_DOCKER_IMAGE_VERSION} \
-		sh -c 'cd /; pip install -r requirements.txt -q; mkdocs serve -a 0.0.0.0:8000'
+include docs-new/Makefile
 
 yamllint:
 	@docker run --rm -t -v $(PWD):/data cytopia/yamllint:$(YAMLLINT_VERSION) .

docs-new/.htmltest.yml

@@ -0,0 +1,13 @@
+CheckDoctype: false
+IgnoreDirectoryMissingTrailingSlash: true
+IgnoreDirs:
+  - favicons
+  - community/
+IgnoreURLs:
+  - "linkedin.com"
+  - "localhost"
+  - "twitter.com"
+  - "fonts.gstatic.com"
+  - "github.com/keptn/lifecycle-toolkit/edit/main/docs-new"
+StripQueryString: false
+OutputDir: /tmp/.htmltest

docs-new/Makefile

@@ -0,0 +1,72 @@
+ROOT_DIR := $(dir $(realpath $(lastword $(MAKEFILE_LIST))))
+
+# renovate: datasource=docker depName=squidfunk/mkdocs-material
+MKDOCS_DOCKER_IMAGE_VERSION=9.5.1
+MKDOCS_DOCKER_IMAGE=squidfunk/mkdocs-material
+
+INTERACTIVE:=$(shell [ -t 0 ] && echo 1)
+PORT := 8000
+
+DOCKER_CMD := docker run --rm $(INTERACTIVE_FLAG)
+
+ifdef INTERACTIVE
+# is a terminal
+INTERACTIVE_FLAG := -it
+else
+INTERACTIVE_FLAG := -t
+endif
+
+PWD=$(shell pwd)
+
+.PHONY: docs-build
+docs-build:
+	$(DOCKER_CMD) -v ${PWD}/docs-new:/docs-new \
+		-v ${PWD}/mkdocs.yml:/mkdocs.yml \
+		-v ${PWD}/requirements.txt:/requirements.txt \
+		-v ${PWD}/site:/site \
+		-v ${PWD}/.git:/.git \
+		--entrypoint "" \
+		${MKDOCS_DOCKER_IMAGE}:${MKDOCS_DOCKER_IMAGE_VERSION} \
+		sh -c 'cd /; pip install -r requirements.txt -q; mkdocs build'
+
+.PHONY: docs-serve
+docs-serve:
+	$(DOCKER_CMD) -p $(PORT):$(PORT) \
+		-v ${PWD}/docs-new:/docs-new \
+		-v ${PWD}/mkdocs.yml:/mkdocs.yml \
+		-v ${PWD}/requirements.txt:/requirements.txt \
+		-v ${PWD}/site:/site \
+		-v ${PWD}/.git:/.git \
+		--entrypoint "" \
+		${MKDOCS_DOCKER_IMAGE}:${MKDOCS_DOCKER_IMAGE_VERSION} \
+		sh -c 'cd /; pip install -r requirements.txt -q; mkdocs serve -a 0.0.0.0:$(PORT)'
+
+.PHONY: htmltest
+
+# renovate: datasource=docker depName=wjdp/htmltest
+HTMLTEST_VERSION := v0.17.0
+htmltest: docs-build
+	$(DOCKER_CMD) \
+		-v $(PWD)/docs-new/.htmltest.yml:/.htmltest.yml \
+		-v ${PWD}/site:/site \
+		-v ${PWD}/tmp/.htmltest:/tmp/.htmltest \
+		wjdp/htmltest:$(HTMLTEST_VERSION) -c /.htmltest.yml /site
+
+.PHONY: lint lint-fix
+lint: markdownlint
+lint: lint-fix
+
+# Markdown lint configuration
+#
+# - .markdownlintignore holds the configuration for files to be ignored
+# - .markdownlint.yaml contains the rules for markdownfiles
+# renovate: datasource=docker depName=davidanson/markdownlint-cli2-rules
+MDL_DOCKER_VERSION := v0.11.0
+MDL_CMD := docker run -v $(ROOT_DIR)../:/workdir --rm 
+
+.PHONY: markdownlint markdownlint-fix
+markdownlint:
+	$(MDL_CMD) davidanson/markdownlint-cli2-rules:${MDL_DOCKER_VERSION} "**/*.md" 
+
+markdownlint-fix:
+	$(MDL_CMD) --entrypoint="markdownlint-cli2-fix" davidanson/markdownlint-cli2-rules:${MDL_DOCKER_VERSION} "**/*.md" 

docs-new/docs/components/lifecycle-operator/keptn-apps.md

@@ -64,7 +64,7 @@ for the `KeptnApp` resource itself:
   that contain the identifications required
   to run the Keptn observability features.
 * You must manually add the annotations described in
-  [Pre- and post-deployment checks](../../guides/integrate.md#pre--and-post-deployment-checks)
+  [Pre- and post-deployment checks](../../guides/integrate.md#prepost-deployment-checks)
   to the basic `KeptnApp` manifest to define
   the evaluations and tasks you want to run pre- and post-deployment.
 

docs-new/docs/contribute/general/dco.md

@@ -72,13 +72,13 @@ Your builds will fail and can not be merged if the DCO check fails.
 Do any of the following
 to implement the DCO signoff on each commit:
 
-* [Add **-s** or **--signoff**](#sign-off-with-git-commit--s)
+* [Add **-s** or **--signoff**](#sign-off-while-committing)
   to your usual `git commit` commands
 * [Manually add text](#manually-add-text-to-commit-description)
   to your commit body
 * [Automate DCO](#automate-dco)
 
-## Sign off with git commit -s
+## Sign off while committing
 
 Use the **-s** or **--signoff** flag to the `git commit` command
 to sign off on a commit.

docs-new/docs/core-concepts/usecase-orchestrate.md

@@ -47,8 +47,8 @@ example.
 The steps to implement pre- and post-deployment orchestration are:
 
 * [Using this exercise](#using-this-exercise)
-* [Define evaluations to be performed pre- and post-deployment](#define-evaluations-to-be-performed-pre--and-post-deployment)
-* [Define tasks to be performed pre- and post-deployment](#define-tasks-to-be-performed-pre--and-post-deployment)
+* [Define evaluations to be performed pre- and post-deployment](#define-evaluations-to-be-performed-prepost-deployment)
+* [Define tasks to be performed pre- and post-deployment](#define-tasks-to-be-performed-prepost-deployment)
 * [Integrate evaluations and tasks into the cluster](#integrate-evaluations-and-tasks-into-the-cluster)
 
 This is the third of three exercises in the
@@ -82,7 +82,7 @@ you need to do the following:
    which aggregate [workloads](https://kubernetes.io/docs/concepts/workloads/) that are combined into the released product,
    regardless of the tools being used.
 
-## Define evaluations to be performed pre- and post-deployment
+## Define evaluations to be performed pre/post deployment
 
 An `evaluation` is a KeptnMetric that has a defined target value.
 Evaluations are resources that are defined in a
@@ -115,7 +115,7 @@ The `evaluationTarget` is set to be `>4`,
 so this evaluation makes sure that more than 4 CPUs are available.
 You could include objectives and additional metrics in this evaluation.
 
-## Define tasks to be performed pre- and post-deployment
+## Define tasks to be performed pre/post deployment
 
 Tasks are resources that are defined in a
 [KeptnTaskDefinition](../reference/crd-reference/taskdefinition.md)
@@ -169,7 +169,7 @@ is protected by a secret, the task definition also specifies that secret.
 ## Integrate evaluations and tasks into the cluster
 
 Follow the instructions in
-[Annotate workload](../guides/integrate.md#pre--and-post-deployment-checks)
+[Annotate workload](../guides/integrate.md#prepost-deployment-checks)
 to integrate the evaluations and tasks you defined
 into the cluster
 by applying annotations to the `Deployment` resource.