Improve documentation rendering for GitHub Pages (#1558)

arangodb · Jan 8, 2024 · 2815e71 · 2815e71
1 parent 833d890
commit 2815e71
Show file tree

Hide file tree

Showing 94 changed files with 570 additions and 141 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,6 +1,7 @@
 # Change Log
 
 ## [master](https://github.com/arangodb/kube-arangodb/tree/master) (N/A)
+- (Documentation) Improve documentation rendering for GitHub Pages
 
 ## [1.2.36](https://github.com/arangodb/kube-arangodb/tree/1.2.36) (2024-01-08)
 - (Documentation) Improvements and fixes for rendered documentation (GH pages)

diff --git a/README.md b/README.md
@@ -2,17 +2,29 @@
 
 [![Docker Pulls](https://img.shields.io/docker/pulls/arangodb/kube-arangodb.svg)](https://hub.docker.com/r/arangodb/kube-arangodb/)
 
-ArangoDB Kubernetes Operator helps to run ArangoDB deployments
-on Kubernetes clusters.
+The ArangoDB Kubernetes Operator (`kube-arangodb`) is a set of operators
+that you deploy in your Kubernetes cluster to:
+- Manage deployments of the [ArangoDB database](https://arangodb.com/)
+- Manage backups
+- Provide `PersistentVolumes` on local storage of your nodes for optimal storage performance.
+- Configure ArangoDB Datacenter-to-Datacenter Replication
+
+Each of these uses involves a different custom resource:
+- Use an [ArangoDeployment resource](docs/deployment-resource-reference.md) to create an ArangoDB database deployment.
+- Use an [ArangoMember resource](docs/api/ArangoMember.V1.md) to observe and adjust individual deployment members.
+- Use an [ArangoBackup](docs/backup-resource.md) and [ArangoBackupPolicy](docs/backuppolicy-resource.md) resources to create ArangoDB backups.
+- Use an [ArangoLocalStorage resource](docs/storage-resource.md) to provide local `PersistentVolumes` for optimal I/O performance.
+- Use an [ArangoDeploymentReplication resource](docs/deployment-replication-resource-reference.md) to configure ArangoDB Datacenter-to-Datacenter Replication.
+
+Continue with [Using the ArangoDB Kubernetes Operator](docs/using-the-operator.md)
+to learn how to install the ArangoDB Kubernetes operator and create your first deployment.
 
-To get started, follow the Installation instructions below and/or
-read the [tutorial](docs/using-the-operator.md).  
 
 ## State
 
 The ArangoDB Kubernetes Operator is Production ready.
 
-[Documentation](docs/README.md)
+[Documentation](https://arangodb.github.io/kube-arangodb/)
 
 ### Limits
 

diff --git a/docs/README.md b/docs/README.md
diff --git a/docs/api/ArangoBackup.V1.md b/docs/api/ArangoBackup.V1.md
@@ -1,3 +1,9 @@
+---
+layout: page
+parent: CRD reference
+title: ArangoBackup V1
+---
+
 # API Reference for ArangoBackup V1
 
 ## Spec

diff --git a/docs/api/ArangoBackupPolicy.V1.md b/docs/api/ArangoBackupPolicy.V1.md
@@ -1,3 +1,9 @@
+---
+layout: page
+parent: CRD reference
+title: ArangoBackupPolicy V1
+---
+
 # API Reference for ArangoBackupPolicy V1
 
 ## Spec

diff --git a/docs/api/ArangoDeployment.V1.md b/docs/api/ArangoDeployment.V1.md
@@ -1,3 +1,9 @@
+---
+layout: page
+parent: CRD reference
+title: ArangoDeployment V1
+---
+
 # API Reference for ArangoDeployment V1
 
 ## Spec

diff --git a/docs/api/ArangoDeploymentReplication.V1.md b/docs/api/ArangoDeploymentReplication.V1.md
@@ -1,3 +1,9 @@
+---
+layout: page
+parent: CRD reference
+title: ArangoDeploymentReplication V1
+---
+
 # API Reference for ArangoDeploymentReplication V1
 
 ## Spec

diff --git a/docs/api/ArangoLocalStorage.V1Alpha.md b/docs/api/ArangoLocalStorage.V1Alpha.md
@@ -1,3 +1,9 @@
+---
+layout: page
+parent: CRD reference
+title: ArangoLocalStorage V1Alpha
+---
+
 # API Reference for ArangoLocalStorage V1Alpha
 
 ## Spec

diff --git a/docs/api/ArangoMLBatchJob.V1Alpha1.md b/docs/api/ArangoMLBatchJob.V1Alpha1.md
@@ -1,3 +1,9 @@
+---
+layout: page
+parent: CRD reference
+title: ArangoMLBatchJob V1Alpha1
+---
+
 # API Reference for ArangoMLBatchJob V1Alpha1
 
 ## Spec

diff --git a/docs/api/ArangoMLCronJob.V1Alpha1.md b/docs/api/ArangoMLCronJob.V1Alpha1.md
@@ -1,3 +1,9 @@
+---
+layout: page
+parent: CRD reference
+title: ArangoMLCronJob V1Alpha1
+---
+
 # API Reference for ArangoMLCronJob V1Alpha1
 
 ## Spec

diff --git a/docs/api/ArangoMLExtension.V1Alpha1.md b/docs/api/ArangoMLExtension.V1Alpha1.md
@@ -1,3 +1,9 @@
+---
+layout: page
+parent: CRD reference
+title: ArangoMLExtension V1Alpha1
+---
+
 # API Reference for ArangoMLExtension V1Alpha1
 
 ## Spec

diff --git a/docs/api/ArangoMLStorage.V1Alpha1.md b/docs/api/ArangoMLStorage.V1Alpha1.md
@@ -1,3 +1,9 @@
+---
+layout: page
+parent: CRD reference
+title: ArangoMLStorage V1Alpha1
+---
+
 # API Reference for ArangoMLStorage V1Alpha1
 
 ## Spec

diff --git a/docs/api/ArangoMember.V1.md b/docs/api/ArangoMember.V1.md
@@ -1,3 +1,9 @@
+---
+layout: page
+parent: CRD reference
+title: ArangoMember V1
+---
+
 # API Reference for ArangoMember V1
 
 ## Spec

diff --git a/docs/api/README.md b/docs/api/README.md
@@ -1,13 +1,6 @@
-# Custom Resources API Reference
-
- - [ArangoBackup.V1](./ArangoBackup.V1.md)
- - [ArangoBackupPolicy.V1](./ArangoBackupPolicy.V1.md)
- - [ArangoDeployment.V1](./ArangoDeployment.V1.md)
- - [ArangoDeploymentReplication.V1](./ArangoDeploymentReplication.V1.md)
- - [ArangoLocalStorage.V1Alpha](./ArangoLocalStorage.V1Alpha.md)
- - [ArangoMLBatchJob.V1Alpha1](./ArangoMLBatchJob.V1Alpha1.md)
- - [ArangoMLCronJob.V1Alpha1](./ArangoMLCronJob.V1Alpha1.md)
- - [ArangoMLExtension.V1Alpha1](./ArangoMLExtension.V1Alpha1.md)
- - [ArangoMLStorage.V1Alpha1](./ArangoMLStorage.V1Alpha1.md)
- - [ArangoMember.V1](./ArangoMember.V1.md)
-
+---
+layout: page
+title: CRD reference
+has_children: true
+nav_order: 3
+---
diff --git a/docs/backup-resource.md b/docs/backup-resource.md
@@ -1,3 +1,9 @@
+---
+layout: page
+parent: Custom resources overview
+title: ArangoBackup
+---
+
 # ArangoBackup Custom Resource
 
 [Full CustomResourceDefinition reference ->](./api/ArangoBackup.V1.md)

diff --git a/docs/backuppolicy-resource.md b/docs/backuppolicy-resource.md
@@ -1,3 +1,9 @@
+---
+layout: page
+parent: Custom resources overview
+title: ArangoBackupPolicy
+---
+
 # ArangoBackupPolicy Custom Resource
 
 [Full CustomResourceDefinition reference ->](./api/ArangoBackupPolicy.V1.md)

diff --git a/docs/crds.md b/docs/crds.md
@@ -1,3 +1,11 @@
+---
+layout: page
+has_children: true
+title: Custom resources overview
+nav_order: 4
+has_toc: false
+---
+
 # Custom resources overview
 
 Main CRDs:

diff --git a/docs/dashboards.md b/docs/dashboards.md
@@ -1,3 +1,9 @@
+---
+layout: page
+nav_order: 20
+title: Operator dashboard
+---
+
 # Deployment Operator Dashboards
 
 ### Dashboard UI now is deprecated and will be removed in next minor version
diff --git a/docs/deployment-replication-resource-reference.md b/docs/deployment-replication-resource-reference.md
@@ -1,3 +1,9 @@
+---
+layout: page
+parent: Custom resources overview
+title: ArangoDeploymentReplication
+---
+
 # ArangoDeploymentReplication Custom Resource
 
 #### Enterprise Edition only
@@ -90,10 +96,12 @@ running in Kubernetes:
 
 2. Extract the access package from the source ArangoDB cluster.
 
+   <!-- {% raw %} -->
    ```bash
    kubectl get secret src-accesspackage --template='{{index .data "accessPackage.yaml"}}' | \
      base64 -D > accessPackage.yaml
    ```
+   <!-- {% endraw %} -->
 
 3. Configure the source DNS names.
 
@@ -232,9 +240,12 @@ The process for creating and using an access package for authentication at the s
 - Wait for the `ArangoDeployment` operator to create a `Secret` named `my-access-package`.
 - Extract the access package from the Kubernetes source cluster using:
 
+
+<!-- {% raw %} -->
 ```bash
 kubectl get secret my-access-package --template='{{index .data "accessPackage.yaml"}}' | base64 -D > accessPackage.yaml
 ```
+<!-- {% endraw %} -->
 
 - Insert the secrets found in the access package in the Kubernetes destination cluster using:
 

diff --git a/docs/deployment-resource-reference.md b/docs/deployment-resource-reference.md
@@ -1,3 +1,9 @@
+---
+layout: page
+parent: Custom resources overview
+title: ArangoDeployment
+---
+
 # ArangoDeployment Custom Resource Overview
 
 [Full CustomResourceDefinition reference ->](./api/ArangoDeployment.V1.md)

diff --git a/docs/design/README.md b/docs/design/README.md
@@ -1,12 +1,7 @@
-# ArangoDB operator architecture overview
+---
+layout: page
+title: Design overview
+has_children: true
+nav_order: 5
+---
 
-- [Operator API](./api.md)
-- [Backups](./backup.md)
-- [Constraints for high-availability](./constraints.md)
-- [ArangoDB Exporter](./exporter.md)
-- [Health](./health.md)
-- [Lifecycle hooks and Finalizers](./lifecycle_hooks_and_finalizers.md)
-- [Pod eviction and replacement](./pod_eviction_and_replacement.md)
-- [Kubernetes Pod name versus cluster ID](./pod_name_versus_cluster_id.md)
-- [Resources & labels](./resources_and_labels.md)
-- [Topology awareness](./topology_awareness.md)
diff --git a/docs/design/api.md b/docs/design/api.md
@@ -1,3 +1,9 @@
+---
+layout: page
+title: Operator API
+parent: Design overview
+---
+
 # Operator API
 
 A running operator exposes HTTP and gRPC API listeners to allow retrieving and setting some configuration values programmatically.

diff --git a/docs/design/backup.md b/docs/design/backup.md
@@ -1,3 +1,9 @@
+---
+layout: page
+title: Backups
+parent: Design overview
+---
+
 # ArangoBackup
 
 ## Lifetime

diff --git a/docs/design/constraints.md b/docs/design/constraints.md
@@ -1,3 +1,9 @@
+---
+layout: page
+title: Constraints
+parent: Design overview
+---
+
 # Constraints
 
 The ArangoDB operator tries to honor various constraints to support high availability of

diff --git a/docs/design/exporter.md b/docs/design/exporter.md
@@ -1,3 +1,9 @@
+---
+layout: page
+title: ArangoDB Metrics
+parent: Design overview
+---
+
 # ArangoDB Exporter for Prometheus
 
 This exporter exposes the statistics provided by a specific ArangoDB instance

diff --git a/docs/design/health.md b/docs/design/health.md
@@ -1,3 +1,9 @@
+---
+layout: page
+title: Health checks
+parent: Design overview
+---
+
 # Health checks
 
 ## Liveness Probe

diff --git a/docs/design/lifecycle_hooks_and_finalizers.md b/docs/design/lifecycle_hooks_and_finalizers.md
@@ -1,3 +1,9 @@
+---
+layout: page
+title: Lifecycle hooks and Finalizers
+parent: Design overview
+---
+
 # Lifecycle hooks & Finalizers
 
 The ArangoDB operator expects full control of the `Pods` and `PersistentVolumeClaims` it creates.

diff --git a/docs/design/pod_eviction_and_replacement.md b/docs/design/pod_eviction_and_replacement.md
@@ -1,3 +1,9 @@
+---
+layout: page
+title: Pod eviction and replacement
+parent: Design overview
+---
+
 # Pod Eviction & Replacement
 
 This chapter specifies the rules around evicting pods from nodes and