chore: introduce dev environment setup for documentation (#2609)

Signed-off-by: odubajDT <[email protected]>
Signed-off-by: Moritz Wiesinger <[email protected]>
Signed-off-by: odubajDT <[email protected]>
Co-authored-by: Moritz Wiesinger <[email protected]>

.github/actions/spelling/expect.txt

@@ -684,3 +684,4 @@ yml
 YOURNAME
 yourregistry
 youtube
+squidfunk

.gitignore

@@ -52,3 +52,5 @@ readme-generator-for-helm/
 /out.yaml
 /test.yaml
 **helm_tests_output.yaml
+
+/docs-new/site

Makefile

@@ -4,6 +4,10 @@
 KUSTOMIZE_VERSION?=v5.2.1
 CHART_APPVERSION ?= v0.9.0 # x-release-please-version
 
+# renovate: datasource=docker depName=squidfunk/mkdocs-material
+MKDOCS_DOCKER_IMAGE_VERSION=9.4.14
+MKDOCS_DOCKER_IMAGE=squidfunk/mkdocs-material
+
 # renovate: datasource=docker depName=cytopia/yamllint
 YAMLLINT_VERSION ?= alpine
 
@@ -134,9 +138,29 @@ 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 \
+		--entrypoint "" \
+		${MKDOCS_DOCKER_IMAGE}:${MKDOCS_DOCKER_IMAGE_VERSION} \
+		sh -c 'cd /; pip install -r requirements.txt -q; mkdocs build -q'
+
+.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 \
+		--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'
+
 yamllint:
 	@docker run --rm -t -v $(PWD):/data cytopia/yamllint:$(YAMLLINT_VERSION) .
 

docs-new/CONTRIBUTING.md

@@ -0,0 +1,39 @@
+# Contribute to the Keptn documentation
+
+This document provides information about contributing to
+the [Keptn documentation](https://lifecycle.keptn.sh/docs/),
+which is part of the [Keptn](https://keptn.sh) website.
+
+The Keptn documentation is authored with
+[markdown](https://www.markdownguide.org/basic-syntax/)
+and rendered using
+[MkDocs](https://www.mkdocs.org/).
+
+We welcome and encourage contributions of all levels.
+You can make modifications using the GitHub editor;
+this works well for small modifications but,
+if you are making significant changes,
+you may find it better to fork and clone the repository
+and make changes using the text editor or IDE of your choice.
+You can also run the website locally
+to check the rendered documentation
+and then push your changes to the repository as a pull request.
+
+If you need help getting started,
+feel free to ask for help on the `#keptn` channel on the [CNCF Slack](https://cloud-native.slack.com).
+We were all new to this once and are happy to help you!
+
+## Building the Documentation Locally
+
+To build and deploy the documentation in a container, execute
+
+```shell
+make docs-serve
+```
+
+This will setup a container, install all needed dependencies,
+build the documentation and serve it.
+
+The URL on which your local documentation website is deployed will be
+displayed in the logs.
+By default this should be `http://0.0.0.0:8000/`

mkdocs.yml

@@ -56,7 +56,8 @@ plugins:
   - social
   - include-markdown:
       trailing_newlines: false
-  - git-revision-date-localized
+  - git-revision-date-localized:
+      fallback_to_build_date: true
 
 nav:
   - Home: