[Task] Update tronador docs with submodule mkdocs SA 5303 (#20)

* Added git submodule theme common for tronador docs

* Modified gitmodules and vale to shift vocabulary

* Removed submodule vocabulary tracking

* Updated mkdocs yml

* Updated mkdocs yml theme override

* Updated github workflows to the latest

* Updated content config file md spell check issue

* Updated config file spell check issue

* Updated config file md

* Updated the config_file for spell check fix

* Replaced deadlinks with the working ones

* Removed footer logo from override

* Modified the theme override for docs shifted logo and modified mkdocs yml

* Updated theme common

* Modified md files for notes indent issue

* Updated config file md

.github/workflows/pull_request.yaml

@@ -3,17 +3,17 @@ name: Pull Request
 on:
   pull_request:
     branches:
-      - 'main'
+      - "main"
 
 jobs:
   qa:
-    uses: stakater/.github/.github/workflows/[email protected].62
+    uses: stakater/.github/.github/workflows/[email protected].75
     with:
       MD_CONFIG: .github/md_config.json
       DOC_SRC: content
       MD_LINT_CONFIG: .markdownlint.yaml
   build:
-    uses: stakater/.github/.github/workflows/[email protected].62
+    uses: stakater/.github/.github/workflows/[email protected].75
     with:
       DOCKER_FILE_PATH: Dockerfile
     secrets:

.github/workflows/push.yaml

@@ -3,11 +3,11 @@ name: Push
 on:
   push:
     branches:
-      - 'main'
+      - "main"
 
 jobs:
   push:
-    uses: stakater/.github/.github/workflows/[email protected].62
+    uses: stakater/.github/.github/workflows/[email protected].75
     with:
       DOCKER_FILE_PATH: Dockerfile
       RELEASE_BRANCH: main

.github/workflows/release.yaml

@@ -7,6 +7,6 @@ on:
 
 jobs:
   release:
-    uses: stakater/.github/.github/workflows/[email protected].62
+    uses: stakater/.github/.github/workflows/[email protected].75
     secrets:
       SLACK_WEBHOOK_URL: ${{ secrets.STAKATER_DELIVERY_SLACK_WEBHOOK }}

.gitignore

@@ -20,3 +20,6 @@ node_modules
 
 # Build files
 site/
+
+# yml files
+mkdocs.yml

.gitmodules

@@ -1,3 +1,3 @@
-[submodule "vocabulary"]
-	path = vocabulary
-	url = [email protected]:stakater/vocabulary.git
+[submodule "theme_common"]
+	path = theme_common
+	url = [email protected]:stakater/stakater-docs-mkdocs-theme.git

.vale.ini

@@ -1,7 +1,8 @@
-StylesPath = "vocabulary/styles"
+StylesPath = styles
 MinAlertLevel = warning
 
-Vocab = "Stakater"
+Packages = https://github.com/stakater/vale-package/releases/download/v0.0.17/Stakater.zip
+Vocab = Stakater
 
 # Only check MarkDown files
 [*.md]

Dockerfile

@@ -1,6 +1,6 @@
 FROM python:3.12-alpine as builder
 
-RUN pip3 install mkdocs-material mkdocs-mermaid2-plugin
+RUN pip3 install mkdocs-mermaid2-plugin mkdocs-table-reader-plugin mkdocs-include-markdown-plugin
 
 # set workdir
 RUN mkdir -p $HOME/application
@@ -10,6 +10,7 @@ WORKDIR $HOME/application
 COPY --chown=1001:root . .
 
 # build the docs
+RUN chmod +x prepare_theme.sh && ./prepare_theme.sh
 RUN mkdocs build
 
 FROM nginxinc/nginx-unprivileged:1.26-alpine as deploy

content/config_file.md

@@ -1,6 +1,6 @@
 # Config File
 
-The Tronador config file should contain configuration elements for the `Environment` CR in yaml format. The config file will be used in conjunction with the `create-environment` cluster task to automatically create an `Environment` CR in the cluster.
+The Tronador config file should contain configuration elements for the `Environment` CR in `YAML` format. The config file will be used in conjunction with the `create-environment` cluster task to automatically create an `Environment` CR in the cluster.
 
 ```yaml
 application:
@@ -9,8 +9,8 @@ application:
     application:
       deployment:
         image:
-          repository: {{APPLICATION_IMAGE_NAME}}
-          tag: {{APPLICATION_IMAGE_TAG}}
+          repository: { { APPLICATION_IMAGE_NAME } }
+          tag: { { APPLICATION_IMAGE_TAG } }
   values_from:
     - secretKeyRef:
         name: default-values
@@ -56,8 +56,8 @@ then you must populate your `value_overrides` field as follows:
 value_overrides:
   deployment:
     image:
-      repository: {{APPLICATION_IMAGE_NAME}}
-      tag: {{APPLICATION_IMAGE_TAG}}
+      repository: { { APPLICATION_IMAGE_NAME } }
+      tag: { { APPLICATION_IMAGE_TAG } }
 ```
 
 !!! v-pre

content/troubleshooting.md

@@ -7,25 +7,25 @@
 
 Environment provisioning takes a few minutes to complete, since there is a lot of steps involved that can take some time (image creation, ArgoCD sync, Helm Operator reconcile, etc). Please take a look at the [workflow for Tronador](./workflow.md) to see how the process works. If the environment is still not provisioned after a few minutes, you can use the following steps to get an idea of why it is taking so long:
 
-* Check your cluster's PipelineRun resource to check its status. If any task fails, you can look at the logs of the failed task to see what went wrong.
+- Check your cluster's PipelineRun resource to check its status. If any task fails, you can look at the logs of the failed task to see what went wrong.
 
 ![Pipeline guide](./images/pipeline-ts.png)
 
 ![A successful pipeline run](./images/pipeline-success.png)
 
-* View your GitOps repository to verify that the Environment CR is pushed to it.
+- View your GitOps repository to verify that the Environment CR is pushed to it.
 
 ![Environment pushed](./images/gitops.png)
 
-* Confirm that the Environment CR is pushed to your cluster by checking the status of the ArgoCD Application managing its sync.
+- Confirm that the Environment CR is pushed to your cluster by checking the status of the ArgoCD Application managing its sync.
 
 ![Relevant ArgoCD Application synced](./images/argocd.png)
 
-* Check the status of the created resources to see if they are in a good state.
+- Check the status of the created resources to see if they are in a good state.
 
 ![Verify that HR is created](./images/hr-ts.png)
 
-* If everything above looks good, then the pods might be in a failing state. Check the pods deployed to your provisioned namespace and view their events to see if there are any failures, and why. Most likely the issue is a lack of imagePullSecrets in the provisioned namespace.
+- If everything above looks good, then the pods might be in a failing state. Check the pods deployed to your provisioned namespace and view their events to see if there are any failures, and why. Most likely the issue is a lack of imagePullSecrets in the provisioned namespace.
 
 Those secrets can be added using [Tronador Config](./tronador_config.md) by mentioning the resources in the CR, which will deploy those resources in all DTE Namespaces.
-This can also be done by [Multi Tenant Operator's](https://docs.stakater.com/mto/main/index.html) [TemplateGroupInstance](https://docs.stakater.com/mto/latest/how-to-guides/template-group-instance.html) by setting the proper label in your Tronador config file.
+This can also be done by [Multi Tenant Operator's](https://docs.stakater.com/mto/main/index.html) [TemplateGroupInstance](https://docs.stakater.com/mto/latest/crds-api-reference/template-group-instance.html) by setting the proper label in your Tronador config file.

content/workflow.md

@@ -22,13 +22,13 @@ application:
     application:
       deployment:
         image:
-          repository: {{APPLICATION_IMAGE_NAME}}
-          tag: {{APPLICATION_IMAGE_TAG}}
+          repository: { { APPLICATION_IMAGE_NAME } }
+          tag: { { APPLICATION_IMAGE_TAG } }
 ```
 
 ### GitHub Event
 
- GitHub (or any other repository management system) events are used to trigger the Tronador pipeline. The pipeline is triggered whenever a PR is opened for a repository that supports Tronador.
+GitHub (or any other repository management system) events are used to trigger the Tronador pipeline. The pipeline is triggered whenever a PR is opened for a repository that supports Tronador.
 
 ### Tekton Pipeline
 
@@ -110,7 +110,7 @@ spec:
       sourceRef:
         kind: GitRepository
         name: dte-master
-      version: '*'
+      version: "*"
   install:
     remediation:
       retries: 60
@@ -139,15 +139,15 @@ spec:
   ref:
     branch: master
   timeout: 20s
-  url: 'https://github.com/stakater-lab/stakater-nordmart-inventory'
+  url: "https://github.com/stakater-lab/stakater-nordmart-inventory"
 ```
 
 ### Secrets management
 
 Secrets for the Helm chart to be deployed are currently passed along from the Tronador config file, to the Helm release.
 Secrets for Helm chart and other required resources like image pull secret can be brought into Environment owned namespaces using [Tronador Config](./tronador_config.md) CR.
 
-You can also use [Multi Tenant Operator's](https://docs.stakater.com/mto/main/index.html) [TemplateGroupInstance](https://docs.stakater.com/mto/latest/how-to-guides/template-group-instance.html) to pass secrets to the namespace that will be provisioned by the Environment by setting the proper label in your Tronador config file. An example for this workflow is [provided here](https://docs.stakater.com/mto/latest/reference-guides/deploying-templates.html#deploying-template-to-namespaces-via-templategroupinstances).
+You can also use [Multi Tenant Operator's](https://docs.stakater.com/mto/main/index.html) [TemplateGroupInstance](https://docs.stakater.com/mto/latest/crds-api-reference/template-group-instance.html) to pass secrets to the namespace that will be provisioned by the Environment by setting the proper label in your Tronador config file. An example for this workflow is [provided here](https://docs.stakater.com/mto/latest/tutorials/distributing-resources/distributing-manifests.html#deploying-template-to-n[…]a-templategroupinstances).
 
 ### Application snapshot deployed
 

prepare_theme.sh

@@ -0,0 +1,3 @@
+pip install -r theme_common/requirements.txt
+python theme_common/scripts/combine_theme_resources.py theme_common/resources theme_override/resources dist/_theme
+python theme_common/scripts/combine_mkdocs_config_yaml.py theme_common/mkdocs.yml theme_override/mkdocs.yml mkdocs.yml

theme_override/mkdocs.yml

@@ -0,0 +1,20 @@
+site_name: Stakater Tronador
+docs_dir: content
+site_url: https://docs.stakater.com/tronador/
+repo_url: https://github.com/stakater/tronador-docs
+edit_uri: blob/main/content/
+use_directory_urls: false
+theme:
+  prev_next_buttons_location: none
+  logo: assets/images/favicon.svg
+  favicon: assets/images/favicon.svg
+nav:
+  - Tronador:
+      - index.md
+      - environment.md
+      - tronador_config.md
+      - config_file.md
+      - cluster_task.md
+      - workflow.md
+      - troubleshooting.md
+      - changelog.md