[PRA-153] docs: Add autogenerated metadata description (#186)

izmalk · theoctober19th · deusebio · web-flow · commit 62760264acb8 · 2026-02-04T14:39:47.000Z
* Add autogenerated metadata description

Signed-off-by: Vladimir Izmalkov &lt;48120135+izmalk@users.noreply.github.com&gt;
Co-authored-by: Bikalpa Dhakal &lt;theoctober19th@gmail.com&gt;
Co-authored-by: deusebio &lt;edeusebio85@gmail.com&gt;
diff --git a/docs/Makefile b/docs/Makefile
@@ -109,7 +109,7 @@ pa11y: pa11y-install html
 	find $(BUILDDIR) -name *.html -print0 | xargs -n 1 -0 $(PA11Y)
 
 lint-md: pymarkdownlnt-install
-	@. $(VENV); pymarkdownlnt --config $(SPHINXDIR)/.pymarkdown.json scan --recurse --exclude=./$(SPHINXDIR)/** $(SOURCEDIR)
+	@. $(VENV); pymarkdownlnt --config $(SPHINXDIR)/.pymarkdown.json scan --recurse --exclude=$(SPHINXDIR)/** $(SOURCEDIR)
 
 vale-install: install
 	@. $(VENV); test -d $(SPHINXDIR)/venv/lib/python*/site-packages/vale || pip install rst2html vale
diff --git a/docs/explanation/component-overview.md b/docs/explanation/component-overview.md
@@ -1,3 +1,9 @@
+---
+myst:
+  html_meta:
+    description: "Understand the components of Charmed Apache Spark: spark8t, OCI images, spark-client snap, and Juju charms for Kubernetes deployments."
+---
+
 (explanation-component-overview)=
 # Components overview
 
diff --git a/docs/explanation/configuration.md b/docs/explanation/configuration.md
@@ -1,3 +1,9 @@
+---
+myst:
+  html_meta:
+    description: "Understand hierarchical configuration management in Charmed Apache Spark with group, user, environment, and session-level settings."
+---
+
 (explanation-configuration)=
 # Configuration management
 
diff --git a/docs/explanation/cryptography.md b/docs/explanation/cryptography.md
@@ -1,3 +1,9 @@
+---
+myst:
+  html_meta:
+    description: "Learn about cryptography practices in Charmed Apache Spark including resource checksums, image verification, and source code integrity."
+---
+
 (explanation-cryptography)=
 # Cryptography
 
diff --git a/docs/explanation/index.md b/docs/explanation/index.md
@@ -1,3 +1,9 @@
+---
+myst:
+  html_meta:
+    description: "In-depth explanations of Charmed Apache Spark components, security, cryptography, configuration management, and monitoring concepts."
+---
+
 (explanation-index)=
 # Explanation
 
diff --git a/docs/explanation/monitoring.md b/docs/explanation/monitoring.md
@@ -1,3 +1,9 @@
+---
+myst:
+  html_meta:
+    description: "Understand monitoring architecture in Charmed Apache Spark with Spark History Server and Canonical Observability Stack (COS) integration."
+---
+
 (explanation-monitoring)=
 # Monitoring
 
diff --git a/docs/explanation/security.md b/docs/explanation/security.md
@@ -1,3 +1,9 @@
+---
+myst:
+  html_meta:
+    description: "Security hardening guide for Charmed Apache Spark covering Kubernetes, Juju, encryption, authentication, and secure deployment practices."
+---
+
 (explanation-security)=
 # Security hardening guide
 
diff --git a/docs/explanation/trademarks.md b/docs/explanation/trademarks.md
@@ -1,3 +1,9 @@
+---
+myst:
+  html_meta:
+    description: "Trademark information for Apache Spark, Apache Kyuubi, and related Apache Software Foundation trademarks used in this documentation."
+---
+
 (explanation-trademarks)=
 # Trademarks
 
diff --git a/docs/how-to/apache-kyuubi/back-up-and-restore.md b/docs/how-to/apache-kyuubi/back-up-and-restore.md
@@ -1,3 +1,9 @@
+---
+myst:
+  html_meta:
+    description: "How-to guide for backing up and restoring data for Charmed Apache Kyuubi using object storage and PostgreSQL metastore."
+---
+
 (how-to-apache-kyuubi-back-up-and-restore)=
 # How to to back up and restore data for Charmed Apache Kyuubi
 
diff --git a/docs/how-to/apache-kyuubi/encryption-and-passwords.md b/docs/how-to/apache-kyuubi/encryption-and-passwords.md
@@ -1,3 +1,9 @@
+---
+myst:
+  html_meta:
+    description: "How-to guide for enabling TLS encryption and manage passwords for Charmed Apache Kyuubi K8s using Juju secrets and certificate relations."
+---
+
 (how-to-apache-kyuubi-encryption-and-passwords)=
 # Manage encryption and passwords
 
diff --git a/docs/how-to/apache-kyuubi/external-connections.md b/docs/how-to/apache-kyuubi/external-connections.md
@@ -1,3 +1,9 @@
+---
+myst:
+  html_meta:
+    description: "How-to guide for configuring external connections for Apache Kyuubi on Kubernetes using LoadBalancer or NodePort service types."
+---
+
 (how-to-apache-kyuubi-external-connections)=
 # External connections
 
diff --git a/docs/how-to/apache-kyuubi/external-metastore.md b/docs/how-to/apache-kyuubi/external-metastore.md
@@ -1,3 +1,9 @@
+---
+myst:
+  html_meta:
+    description: "How-to guide for configuring an external PostgreSQL metastore for Charmed Apache Kyuubi K8s instead of the embedded database."
+---
+
 (how-to-apache-kyuubi-external-metastore)=
 # External metastore
 
diff --git a/docs/how-to/apache-kyuubi/gpu.md b/docs/how-to/apache-kyuubi/gpu.md
@@ -1,3 +1,9 @@
+---
+myst:
+  html_meta:
+    description: "How-to guide for configuring GPU support for Charmed Apache Kyuubi to run hardware-accelerated queries with NVIDIA RAPIDS on Kubernetes."
+---
+
 (how-to-apache-kyuubi-gpu)=
 # How to configure GPU support for Charmed Apache Kyuubi
 
diff --git a/docs/how-to/apache-kyuubi/index.md b/docs/how-to/apache-kyuubi/index.md
@@ -1,3 +1,9 @@
+---
+myst:
+  html_meta:
+    description: "How-to guides for deploying and managing Charmed Apache Kyuubi on Kubernetes with encryption, external connections, and backups."
+---
+
 (how-to-apache-kyuubi-index)=
 # Apache Kyuubi
 
diff --git a/docs/how-to/apache-kyuubi/integrate-with-applications.md b/docs/how-to/apache-kyuubi/integrate-with-applications.md
@@ -1,3 +1,9 @@
+---
+myst:
+  html_meta:
+    description: "How-to guide for integrating Charmed Apache Kyuubi with charmed and non-charmed applications using data-integrator and kyuubi_client interface."
+---
+
 (how-to-apache-kyuubi-integrate-with-applications)=
 # Integrate with applications
 
diff --git a/docs/how-to/apache-kyuubi/upgrade.md b/docs/how-to/apache-kyuubi/upgrade.md
@@ -1,3 +1,9 @@
+---
+myst:
+  html_meta:
+    description: "How-to guide for performing in-place upgrades for Charmed Apache Kyuubi K8s to update the charm and workload to newer versions."
+---
+
 (how-to-apache-kyuubi-upgrade)=
 # How to upgrade
 
diff --git a/docs/how-to/deploy/environment.md b/docs/how-to/deploy/environment.md
@@ -1,3 +1,9 @@
+---
+myst:
+  html_meta:
+    description: "How-to guide for setting up Kubernetes clusters and object storage for Charmed Apache Spark on MicroK8s, AWS EKS, Azure AKS, and Canonical K8s."
+---
+
 (how-to-deploy-environment)=
 # How to set up a K8s cluster for Apache Spark
 
diff --git a/docs/how-to/deploy/index.md b/docs/how-to/deploy/index.md
@@ -1,3 +1,9 @@
+---
+myst:
+  html_meta:
+    description: "Deployment guides for setting up Kubernetes environments and deploying Charmed Apache Spark and Kyuubi with Juju."
+---
+
 (how-to-deploy-index)=
 # Deploy
 
diff --git a/docs/how-to/deploy/kyuubi.md b/docs/how-to/deploy/kyuubi.md
@@ -1,3 +1,9 @@
+---
+myst:
+  html_meta:
+    description: "How-to guide for deploying Charmed Apache Kyuubi on Kubernetes with Juju for serverless SQL queries on data lakes with Apache Spark."
+---
+
 (how-to-deploy-kyuubi)=
 # Deploy Charmed Apache Kyuubi
 
diff --git a/docs/how-to/deploy/spark.md b/docs/how-to/deploy/spark.md
@@ -1,3 +1,9 @@
+---
+myst:
+  html_meta:
+    description: "How-to guide for deploying Charmed Apache Spark on Kubernetes with Juju, including object storage, monitoring, and log aggregation integration."
+---
+
 (how-to-deploy-spark)=
 # Deploy Charmed Apache Spark
 
diff --git a/docs/how-to/enable-monitoring.md b/docs/how-to/enable-monitoring.md
@@ -1,3 +1,9 @@
+---
+myst:
+  html_meta:
+    description: "How-to guide for enabling and configuring monitoring for Charmed Apache Spark with Canonical Observability Stack (COS) integration."
+---
+
 (how-to-monitoring)=
 # Enable and configuring monitoring
 
diff --git a/docs/how-to/index.md b/docs/how-to/index.md
@@ -1,3 +1,9 @@
+---
+myst:
+  html_meta:
+    description: "How-to guides for deploying, configuring, and managing Charmed Apache Spark and Kyuubi on Kubernetes with monitoring and security."
+---
+
 (how-to-index)=
 # How-To guides
 
diff --git a/docs/how-to/manage-service-accounts/index.md b/docs/how-to/manage-service-accounts/index.md
@@ -1,3 +1,9 @@
+---
+myst:
+  html_meta:
+    description: "Guides for managing Charmed Apache Spark service accounts using Integration Hub, Python API, and spark-client snap."
+---
+
 (how-to-manage-service-accounts-index)=
 # Manage service accounts
 
diff --git a/docs/how-to/manage-service-accounts/using-integration-hub.md b/docs/how-to/manage-service-accounts/using-integration-hub.md
@@ -1,3 +1,9 @@
+---
+myst:
+  html_meta:
+    description: "How-to guide for configuring Charmed Apache Spark service accounts using the Integration Hub charm with Juju relations and object storage."
+---
+
 (how-to-service-accounts-integration-hub)=
 # Configure service accounts using the Integration Hub charm
 
diff --git a/docs/how-to/manage-service-accounts/using-python.md b/docs/how-to/manage-service-accounts/using-python.md
@@ -1,3 +1,9 @@
+---
+myst:
+  html_meta:
+    description: "How-to guide for managing Charmed Apache Spark service accounts programmatically using the spark8t Python toolkit and API."
+---
+
 (how-to-service-accounts-python)=
 # Manage Service Accounts using the Python API
 
diff --git a/docs/how-to/manage-service-accounts/using-spark-client-snap.md b/docs/how-to/manage-service-accounts/using-spark-client-snap.md
@@ -1,3 +1,9 @@
+---
+myst:
+  html_meta:
+    description: "How-to guide for creating, managing, and configuring Charmed Apache Spark service accounts using the spark-client snap command line interface (CLI)."
+---
+
 (how-to-service-accounts-spark-client)=
 # Manage Charmed Apache Spark service accounts
 
diff --git a/docs/how-to/self-signed-certificates.md b/docs/how-to/self-signed-certificates.md
@@ -1,3 +1,9 @@
+---
+myst:
+  html_meta:
+    description: "How-to guide for configuring Charmed Apache Spark to work with self-signed certificates for secure communication between services."
+---
+
 (how-to-self-signed-certificates)=
 
 # Support self-signed certificates in Charmed Apache Spark
diff --git a/docs/how-to/spark-history-server/auth.md b/docs/how-to/spark-history-server/auth.md
@@ -1,3 +1,9 @@
+---
+myst:
+  html_meta:
+    description: "How-to guide for enabling authentication and authorization for Spark History Server using Canonical Identity Platform integration."
+---
+
 (how-to-spark-history-server-auth)=
 # Enable authorization and authentication with the Spark History Server charm
 
diff --git a/docs/how-to/spark-history-server/expose-web-gui.md b/docs/how-to/spark-history-server/expose-web-gui.md
@@ -1,3 +1,9 @@
+---
+myst:
+  html_meta:
+    description: "How-to guide for exposing the Apache Spark History Server web UI externally using ingress with Traefik on Kubernetes."
+---
+
 (how-to-spark-history-server-expose-web-gui)=
 # Expose the Spark History Server UI
 
diff --git a/docs/how-to/spark-history-server/index.md b/docs/how-to/spark-history-server/index.md
@@ -1,3 +1,9 @@
+---
+myst:
+  html_meta:
+    description: "Guides for deploying and configuring Apache Spark History Server with authentication, authorization, and external access."
+---
+
 (how-to-spark-history-server-index)=
 # Spark History Server
 
diff --git a/docs/how-to/streaming-jobs.md b/docs/how-to/streaming-jobs.md
@@ -1,3 +1,9 @@
+---
+myst:
+  html_meta:
+    description: "How-to guide for configuring and running Apache Spark Streaming jobs against Apache Kafka on Kubernetes using structured streaming."
+---
+
 (how-to-streaming-jobs)=
 # How to run Apache Spark Streaming against Apache Kafka
 
diff --git a/docs/how-to/use-gpu.md b/docs/how-to/use-gpu.md
@@ -1,3 +1,9 @@
+---
+myst:
+  html_meta:
+    description: "How-to guide for enabling GPU acceleration for Apache Spark jobs on Kubernetes using the Apache Spark Rapids plugin with NVIDIA GPUs."
+---
+
 (how-to-use-gpu)=
 # Enabling GPU acceleration
 
diff --git a/docs/how-to/use-k8s-pods.md b/docs/how-to/use-k8s-pods.md
@@ -1,3 +1,9 @@
+---
+myst:
+  html_meta:
+    description: "How-to guide for launching Apache Spark jobs from within a Kubernetes pod on Charmed Kubernetes using Charmed Apache Spark container images."
+---
+
 (how-to-use-k8s-pods)=
 # Working with Charmed Kubernetes from within a pod
 
diff --git a/docs/index.md b/docs/index.md
@@ -1,3 +1,9 @@
+---
+myst:
+  html_meta:
+    description: "Documentation for Charmed Apache Spark on Kubernetes: deploy and operate Spark with Juju, including Kyuubi, Spark History Server, tutorials, and security guidance."
+---
+
 (index)=
 # Charmed Apache Spark documentation
 
diff --git a/docs/reference/contacts.md b/docs/reference/contacts.md
@@ -1,3 +1,9 @@
+---
+myst:
+  html_meta:
+    description: "Contact information for Charmed Apache Spark support including Matrix chat, GitHub issues, and security reporting channels."
+---
+
 (reference-contacts)=
 # Contacts
 
diff --git a/docs/reference/index.md b/docs/reference/index.md
@@ -1,3 +1,9 @@
+---
+myst:
+  html_meta:
+    description: "Reference documentation for Charmed Apache Spark including release notes, system requirements, and contact information."
+---
+
 (reference-index)=
 # Reference
 
diff --git a/docs/reference/releases/index.md b/docs/reference/releases/index.md
@@ -1,3 +1,9 @@
+---
+myst:
+  html_meta:
+    description: "Release notes and version history for all stable releases of Charmed Apache Spark with feature updates and improvements."
+---
+
 (reference-releases-index)=
 # Releases
 
diff --git a/docs/reference/releases/revision-2.md b/docs/reference/releases/revision-2.md
@@ -1,3 +1,9 @@
+---
+myst:
+  html_meta:
+    description: "Release notes for Charmed Apache Spark revision 2 featuring Apache Kyuubi, enhanced security, Azure support, and observability."
+---
+
 (reference-releases-revision-2)=
 # Charmed Apache Spark (revision 2)
 
diff --git a/docs/reference/requirements.md b/docs/reference/requirements.md
@@ -1,3 +1,9 @@
+---
+myst:
+  html_meta:
+    description: "Minimum system requirements for deploying Charmed Apache Spark on Kubernetes including CPU, memory, storage, and network needs."
+---
+
 (reference-requirements)=
 # Minimum system requirements
 
diff --git a/docs/tutorial/1-environment-setup.md b/docs/tutorial/1-environment-setup.md
@@ -1,3 +1,9 @@
+---
+myst:
+  html_meta:
+    description: "Learn how to set up MicroK8s, spark-client snap, MinIO, and Juju on Ubuntu for running Charmed Apache Spark on Kubernetes."
+---
+
 (tutorial-1-environment-setup)=
 # 1. Environment setup
 
diff --git a/docs/tutorial/2-distributed-data-processing.md b/docs/tutorial/2-distributed-data-processing.md
diff --git a/docs/tutorial/3-data-stream-processing.md b/docs/tutorial/3-data-stream-processing.md
diff --git a/docs/tutorial/4-history-server.md b/docs/tutorial/4-history-server.md
diff --git a/docs/tutorial/5-monitoring-with-cos.md b/docs/tutorial/5-monitoring-with-cos.md
diff --git a/docs/tutorial/6-apache-kyuubi.md b/docs/tutorial/6-apache-kyuubi.md
diff --git a/docs/tutorial/7-wrapping-up.md b/docs/tutorial/7-wrapping-up.md
diff --git a/docs/tutorial/index.md b/docs/tutorial/index.md
