feat: multiple small improvements on the documentation pages

Author: lentidas

docs/modules/ROOT/nav.adoc

@@ -32,13 +32,13 @@
 * xref:applicationset:ROOT:README.adoc[ApplicationSet]
 * xref:argocd:ROOT:README.adoc[Argo CD]
 * xref:oidc-aws-cognito:ROOT:README.adoc[AWS Cognito OIDC]
-* xref:cert-manager:ROOT:README.adoc[Cert-manager]
+* xref:cert-manager:ROOT:README.adoc[cert-manager]
 * xref:dex:ROOT:README.adoc[Dex]
 * xref:ebs-csi-driver:ROOT:README.adoc[EBS CSI Driver]
 * xref:efs-csi-driver:ROOT:README.adoc[EFS CSI Driver]
 * xref:grafana:ROOT:README.adoc[Grafana]
 * xref:keycloak:ROOT:README.adoc[Keycloak]
-* xref:kube-prometheus-stack:ROOT:README.adoc[Kube-prometheus-stack]
+* xref:kube-prometheus-stack:ROOT:README.adoc[kube-prometheus-stack]
 * xref:loki:ROOT:README.adoc[Loki]
 * xref:metallb:ROOT:README.adoc[MetalLB]
 * xref:minio:ROOT:README.adoc[MinIO]

docs/modules/ROOT/pages/contributing/documentation.adoc

@@ -8,17 +8,17 @@
 
 These documentation pages are written in https://asciidoc.org/[AsciiDoc] format and this website you are is generated using https://antora.org/[Antora].
 
-== How Does Antora Work?
+== How does Antora work?
 
 Antora builds this documentation website from the configurations in an https://docs.antora.org/antora/latest/playbook/[Antora Playbook], which is a YAML file that describes the documentation sources and the output of the build.
 
-=== Content Sources
+=== Content sources
 
 *Our playbook is stored on the root of the {url-main-repo}[main repository] of the DevOps Stack project, in the {url-main-repo}/blob/main/antora-playbook.yml[`antora-playbook.yml` file].* It is this file that defines the content sources (in our case each module of the DevOps Stack project) as well as the tags to take into account when building the documentation.
 
 In this file you'll see a source for the main documentation (that is, the more generic pages stored in the {url-main-repo}[main repository]) and sources for each module on a list under `content.sources`. Each source is defined by a `url` to its repo and a `start_path` that tells Antora where the respective documentation is stored.
 
-=== File Structure
+=== File structure
 
 Each documentation source is expected to have a precise file structure, as documented in extensive detail in the https://docs.antora.org/antora/latest/standard-directories/[Antora documentation].
 
@@ -57,7 +57,7 @@ nav:
 
 In our case, note that we chose to use the tags instead of the branches for versioning the document pages. This is because we release each new version on a single branch but through multiple tags. More explanations about the different versioning methods are available https://docs.antora.org/antora/latest/content-source-versioning-methods/[here].
 
-=== Building The Documentation
+=== Building the documentation
 
 Our documentation is built using a GitHub Action on the main repository, available {url-main-repo}/blob/main/.github/workflows/publish-antora-docs.yaml[here].
 
@@ -69,7 +69,7 @@ TIP: The `README.adoc` of the {url-docker-antora-repo}[customized Docker image]
 
 After generating the documentation, it is then published to the {url-main-repo}/tree/gh-pages[`gh-pages`] branch of the main repository. This branch is then used by GitHub Pages to serve the documentation website.
 
-== Module Documentation
+== Module documentation
 
 The documentation in each module is quite particular in the sense that we have not put the documentation pages on the `docs` folder. Instead we have symbolic links to the `README.adoc` on the root of the repository and to the `README.adoc` inside each variant. Consequently, a typical module as a structure like this:
 
@@ -115,7 +115,7 @@ A module that has variants will be a bit different. The main `README.adoc` shoul
 
 TIP: Check the existing module's documentation pages for examples (the xref:thanos:ROOT:README.adoc[Thanos module] is a good example of a module with variants and the xref:keycloak:ROOT:README.adoc[Keycloak module] is an example without).
 
-=== Terraform Docs Documentation
+=== Terraform Docs documentation
 
 You'll notice that the last sections of the `README.adoc` that are automatically generated by Terraform Docs.
 

docs/modules/ROOT/pages/contributing/general_guidelines.adoc

@@ -9,7 +9,7 @@ The DevOps Stack is a collection of modules, each of them having its own release
 
 TIP: A private GitHub project owned by the https://github.com/orgs/camptocamp/teams/is-devops-stack/[`@camptocamp/is-devops-stack` team] is available https://github.com/orgs/camptocamp/projects/3/[here]. It is a useful way to follow the progress of the PRs and Issues of all the repositories. For more information on how it is implemented, check the xref:ROOT:contributing/project_board.adoc[Project Board] page.
 
-== Development Workflow
+== Development workflow
 
 When a new feature or fix is required, the typical workflow is the following:
 
@@ -24,7 +24,7 @@ The following subsections describe some of the best practices to follow when wor
 * Keep the `main` branch clean, and only merge Pull Requests into it.
 * Create a new branch for each Pull Request. *The name of the branch should be the Jira ticket number, followed by a short description of the work done in the branch*, for example `ISDEVOPS-185-v1-docs`. This will allow the Jira ticket to be automatically linked to the branch and the Pull Request.
 
-=== Commit Messages
+=== Commit messages
 
 * When committing to your branch, you should follow the https://www.conventionalcommits.org/[Conventional Commits] specification. *This will also allow the automated changelog generation to work properly.*
 

docs/modules/ROOT/pages/contributing/modules.adoc

@@ -9,7 +9,7 @@ The DevOps Stack is separated into multiple Terraform modules, each of them cont
 
 In order to improve the readability and maintenance of the code, this page contains some guidelines and explanations behind the creation and development of DevOps Stack modules. There is also a {url-template-repo}[repository template on GitHub] that can be used as a starting point for new modules and you can refer to it while reading this page.
 
-== Basic Modules
+== Basic modules
 
 These kinds of modules are typically the ones that provision clusters and related resources. Good examples of this are the xref:eks:ROOT:README.adoc[Amazon EKS module] and xref:kind:ROOT:README.adoc[KinD module].
 
@@ -56,9 +56,9 @@ IMPORTANT: The `terraform.tf` file should only contain the *minimum required ver
 
 NOTE: Take care to properly describe each entry on the `variables.tf` and `outputs.tf` files. These descriptions are taken into account by Terraform Docs for the automatic documentation of the module.
 
-== Modules With Embedded Helm Charts
+== Modules with embedded Helm charts
 
-These are the more typical modules of the DevOps Stack and are used to deploy the remaining components of the stack. Good examples of this are the xref:argocd:ROOT:README.adoc[Argo CD module] and xref:cert-manager:ROOT:README.adoc[Cert-manager module].
+These are the more typical modules of the DevOps Stack and are used to deploy the remaining components of the stack. Good examples of this are the xref:argocd:ROOT:README.adoc[Argo CD module] and xref:cert-manager:ROOT:README.adoc[cert-manager module].
 
 NOTE: The Argo CD module is a special case, as it is used to deploy the other modules. A bootstrap Argo CD is deployed using resources of the type `helm_release`. This Argo CD is then responsible to deploy the remaining modules, which use resources of the type `argocd_project` and `argocd_application`.
 
@@ -109,6 +109,7 @@ A typical file/folder structure for a module with variants is the following:
 devops-stack-module-template
 ├── aks
 │   ├── extra-variables.tf
+│   ├── extra-terraform.tf
 │   ├── locals.tf
 │   ├── main.tf
 │   ├── outputs.tf
@@ -123,6 +124,7 @@ devops-stack-module-template
 │   └── ...
 ├── eks
 │   ├── extra-variables.tf
+│   ├── extra-terraform.tf
 │   ├── locals.tf
 │   ├── main.tf
 │   ├── outputs.tf
@@ -133,6 +135,7 @@ devops-stack-module-template
 │   └── ...
 ├── kind
 │   ├── extra-variables.tf
+│   ├── extra-terraform.tf
 │   ├── locals.tf
 │   ├── main.tf
 │   ├── outputs.tf
@@ -149,11 +152,12 @@ devops-stack-module-template
 └── version.txt
 ----
 
-IMPORTANT: Note how the `variables.tf` and `terraform.tf` files are symbolic links to the root module. This is to avoid having to maintain the same variables and providers in multiple places.
+IMPORTANT: Note how the `variables.tf` and `terraform.tf` files are symbolic links to the root module. This is to avoid having to maintain the same variables and providers in multiple places. In case there are specific variables and/or providers you need to set, you can simply create new files like `extra-variables.tf` and `extra-terraform.tf` and add them to the variant.
 
 Comparatively to a more basic module, note the following files inside the variants (all the other files are the same and are described above):
 
 . *`extra-variables.tf`* - Contains the definition of the extra input variables of the variant. These are the variables that are specific to the variant and are not present in the root module.
+. *`extra-terraform.tf`* - Contains the versions of the required providers of the variant. These are the providers that are specific to the variant and are not present in the root module.
 . *`locals.tf`* - Contains the definition of the local variables used in the variant. It is here that we define the `helm_values` local that contains only the values specific to the variant. These should be written in HCL and not in YAML. They will be merged with the ones coming from the `helm_values` variable and then passed on to the root module. Afterwards, they will be merged once again, translated to YAML and then passed to the `argocd_application` resource.
 . *`main.tf`* - Usually, this file only contains the call to the root module and passes along all the variables received as well as the modified entries. In specific cases it could also contain other resources specific to the variant. Take a look at this example from the Loki module:
 

docs/modules/ROOT/pages/contributing/project_board.adoc

@@ -29,7 +29,7 @@ After the app creation, an administrator was needed to install it on the organiz
 
 IMPORTANT: The reason to not install the app on all the repositories by default was to further limit the scope of the app, although *this adds the burden of installing it on each repository manually every time a new repository of the DevOps Stack is created*.
 
-=== Centralized Workflow
+=== Centralized workflow
 
 The workflow definition is available in the {url-main-repo}/blob/main/.github/workflows/pr-issues-project.yaml[main repository].
 

docs/modules/ROOT/pages/contributing/release.adoc

@@ -8,13 +8,13 @@ Each module is released and versioned independently. The release process is auto
 
 In the subsections below we will go through the release process in more detail and then explain some steps when manually setting a version.
 
-== Release Please Configuration
+== Release Please configuration
 
 The Release Please tool can be found on https://github.com/googleapis/release-please[this repository] and the GitHub Action we use is available on a https://github.com/google-github-actions/release-please-action[another repository]. Both are maintained by Google.
 
 Every DevOps Stack module contains a GitHub workflow that simply calls a centralized workflow.
 
-=== Centralized Workflow
+=== Centralized workflow
 
 The workflow definition available in the {url-main-repo}/blob/main/.github/workflows/modules-release-please.yaml[main repository].
 
@@ -31,7 +31,7 @@ Note following lines:
 
 . The `extra-files` setting is used to specify additional files that need to be updated when bumping the version. In our case, we also need to update the `variables.tf` file. *This is because we need to statically define the variable `target_revision`, which is used to pin the module version in `argocd_application` resources.*
 
-=== Caller Workflow
+=== Caller workflow
 
 The caller workflow on every module simply points to this workflow and is set to run on every push to the `main` branch. This is the workflow definition:
 
@@ -52,7 +52,7 @@ jobs:
 
 NOTE: Our {url-template-repo}/blob/main/.github/workflows/release-please.yaml[module template] already contains this workflow definition, but with a caveat. To avoid creating releases on the template itself, it was deactivated and you need to re-activate it when creating a new module. The comments on the file are self-explanatory.
 
-== Automatic Versioning
+== Automatic versioning
 
 The commit messages are used to determine the type of release that needs to be created.