Docs prettify (#112)

* docs admonitions * removing test files * Revert "docs admonitions" This reverts commit a76ce78. * docs improvements * removing broken links * updating diagram
aws-observability · Feb 7, 2023 · 0b20234 · 0b20234
1 parent 0c0ac15
commit 0b20234
Show file tree

Hide file tree

Showing 9 changed files with 51 additions and 41 deletions.
diff --git a/docs/concepts.md b/docs/concepts.md
@@ -13,8 +13,9 @@ All examples in this repository require the following tools installed
 To run the examples, you need a set of AWS IAM permissions. You can find an example of minimum
 permissions required [in this file](https://github.com/aws-observability/terraform-aws-observability-accelerator/blob/main/docs/iam/min-iam-policy.json).
 
-> **Note**: The policy resource is set as `*` to allow all resources, this is not a recommended practice.
-You should restrict instead to the ARNs when applicable.
+!!! warning
+    The policy resource is set as `*` to allow all resources, this is not a recommended practice.
+    You should restrict instead to the ARNs when applicable.
 
 ### Terraform states and variables
 
@@ -27,7 +28,8 @@ You can also edit the `terraform.tfvars` files directly and deploy
 with `terraform apply -var-file=terraform.tfvars`. Terraform tfvars file can be useful if
 you need to track changes as part of a Git repository or CI/CD pipeline.
 
-> **Note:** When using `tfvars` files, always be careful to not store and commit any secrets (keys, passwords, ...)
+!!! warning
+    When using `tfvars` files, always be careful to not store and commit any secrets (keys,     passwords, ...)
 
 ## Base module
 
@@ -53,7 +55,7 @@ module "eks_observability_accelerator" {
 }
 ```
 
-You can optionally reuse an existing Amazon Managed Servce for Prometheus Workspace:
+You can optionally reuse an existing Amazon Managed Service for Prometheus Workspace:
 
 ```hcl
 module "eks_observability_accelerator" {
@@ -89,7 +91,9 @@ All the modules come with end-to-end deployable examples.
 
 [Examples](https://github.com/aws-observability/terraform-aws-observability-accelerator/tree/main/examples) put modules together in a ready to deploy terraform configuration as a starting point. With little to no configuration, you can run `terraform apply` and use the deployed resources on your AWS Account.
 
-You can find **workload** examples like [Amazon EKS infrstructure monitoring](https://aws-observability.github.io/terraform-aws-observability-accelerator/eks/) or [monitoring your Amazon Managed Service for Prometheus workspace](https://aws-observability.github.io/terraform-aws-observability-accelerator/workloads/managed-prometheus/) and more.
+You can find **workload** examples like [Amazon EKS infrastructure monitoring](https://aws-observability.github.io/terraform-aws-observability-accelerator/eks/) or [monitoring your Amazon Managed Service for Prometheus workspace](https://aws-observability.github.io/terraform-aws-observability-accelerator/workloads/managed-prometheus/) and more.
+
+![example diagram](images/example-diagram.svg)
 
 
 ## Getting started with AWS Observability services

diff --git a/docs/eks/destroy.md b/docs/eks/destroy.md
@@ -3,9 +3,10 @@
 If you leave this stack running, you will continue to incur charges. To remove all resources
 created by Terraform, [refresh your Grafana API key](https://aws-observability.github.io/terraform-aws-observability-accelerator/eks/#6-grafana-api-key) and run the command below.
 
-Be careful, this command will removing everything created by Terraform. If you wish
-to keep your Amazon Managed Grafana or Amazon Managed Service for Prometheus workspaces. Remove them
-from your terraform state before running the destroy command.
+!!! warning
+    Be careful, this command will removing everything created by Terraform. If you wish
+    to keep your Amazon Managed Grafana or Amazon Managed Service for Prometheus workspaces. Remove them
+    from your terraform state before running the destroy command.
 
 ```bash
 terraform destroy

diff --git a/docs/eks/index.md b/docs/eks/index.md
@@ -22,8 +22,8 @@ on your EKS cluster.
 
 ## Prerequisites
 
-Make sure to complete the [prerequisites section](https://aws-observability.github.io/terraform-aws-observability-accelerator/concepts/#prerequisites)
-before proceeding.
+!!! note
+    Make sure to complete the [prerequisites section](https://aws-observability.github.io/terraform-aws-observability-accelerator/concepts/#prerequisites) before proceeding.
 
 ## Setup
 
@@ -132,8 +132,8 @@ Open the Amazon Managed Service for Prometheus console and view the details of y
 
 <img width="1629" alt="image" src="https://user-images.githubusercontent.com/10175027/189301297-4865e75d-2d71-434f-b5d0-9750b3533632.png">
 
-
-To setup your alert receiver, with Amazon SNS, follow [this documentation](https://docs.aws.amazon.com/prometheus/latest/userguide/AMP-alertmanager-receiver.html)
+!!! note
+    To setup your alert receiver, with Amazon SNS, follow [this documentation](https://docs.aws.amazon.com/prometheus/latest/userguide/AMP-alertmanager-receiver.html)
 
 
 ## Custom metrics collection

diff --git a/docs/helpers/new-eks-cluster.md b/docs/helpers/new-eks-cluster.md
@@ -1,6 +1,7 @@
 # Creating a new Amazon EKS cluster with VPC
 
-> Note: This example is a subset from [this EKS Blueprint example](https://github.com/aws-ia/terraform-aws-eks-blueprints/tree/main/examples/eks-cluster-with-new-vpc)
+!!! note
+    This example is a subset from [this EKS Blueprint example](https://github.com/aws-ia/terraform-aws-eks-blueprints/tree/main/examples/eks-cluster-with-new-vpc)
 
 This example deploys the following:
 
@@ -10,8 +11,8 @@ This example deploys the following:
 
 ## Prerequisites
 
-Make sure to complete the [prerequisites section](https://aws-observability.github.io/terraform-aws-observability-accelerator/concepts/#prerequisites)
-before proceeding.
+!!! note
+    Make sure to complete the [prerequisites section](https://aws-observability.github.io/terraform-aws-observability-accelerator/concepts/#prerequisites) before proceeding.
 
 
 ## Setup

diff --git a/docs/images/example-diagram.svg b/docs/images/example-diagram.svg
diff --git a/docs/index.md b/docs/index.md
@@ -3,7 +3,7 @@
 Welcome to the AWS Observability Accelerator for Terraform!
 
 The AWS Observability accelerator is a set of Terraform modules to help you
-configure Observability for your container workloads and environemnts with AWS
+configure Observability for your container workloads and environments with AWS
 Observability services. This project proposes a core module to bootstrap
 your Amazon EKS cluster with the AWS Distro for OpenTelemetry (ADOT) Operator for EKS,
 Amazon Managed Service for Prometheus, Amazon Managed Grafana.
@@ -23,27 +23,28 @@ dashboards and alerts for monitoring:
 - Java/JMX workloads (running on Amazon EKS)
 - Amazon Managed Service for Prometheus workspaces with Amazon CloudWatch
 
-These modules can be directly configured in your exisiting Terraform configurations or ready
+These modules can be directly configured in your existing Terraform configurations or ready
 to be deployed in our packaged
 [examples](https://github.com/aws-observability/terraform-aws-observability-accelerator/tree/main/examples)
 
-We have supporting examples for quick setup such as:
+!!! tip
+    We have supporting examples for quick setup such as:
 
-- Creating an empty Amazon EKS cluster and a VPC
-- Creating and configure an Amazon Managed Grafana workspace with SSO
+    - Creating an empty Amazon EKS cluster and a VPC
+    - Creating and configure an Amazon Managed Grafana workspace with SSO
 
 ## Motivation
 
-To gain deep visibility into your workloads and environements, AWS proposes a
-set of secure, scalabale, highly available, production-grade managed open
+To gain deep visibility into your workloads and environments, AWS proposes a
+set of secure, scalable, highly available, production-grade managed open
 source services such as Amazon Managed Service for Prometheus, Amazon Managed
 Grafana and Amazon OpenSearch.
 
 AWS customers have asked for best-practices and guidance to collect metrics, logs
 and traces from their containerized applications and microservices with ease of
 deployment. Customers can use the AWS Observability Accelerator to configure their
 metrics collection, leveraging [AWS Distro for OpenTelemetry](https://aws-otel.github.io/),
-to have opinionated dashoards and alerts available in only minutes.
+to have opinionated dashboards and alerts available in only minutes.
 
 
 ## Support & Feedback

diff --git a/docs/workloads/java.md b/docs/workloads/java.md
@@ -7,8 +7,8 @@ configuration options on the cluster infrastructure.
 
 ## Prerequisites
 
-Make sure to complete the [prerequisites section](https://aws-observability.github.io/terraform-aws-observability-accelerator/concepts/#prerequisites)
-before proceeding.
+!!! note
+    Make sure to complete the [prerequisites section](https://aws-observability.github.io/terraform-aws-observability-accelerator/concepts/#prerequisites) before proceeding.
 
 ## Setup
 
@@ -118,8 +118,8 @@ Open the Amazon Managed Service for Prometheus console and view the details of y
 
 <img width="1314" alt="image" src="https://user-images.githubusercontent.com/97046295/194904104-09a28577-d149-478e-b0a1-dc21cb7effc1.png">
 
-
-To setup your alert receiver, with Amazon SNS, follow [this documentation](https://docs.aws.amazon.com/prometheus/latest/userguide/AMP-alertmanager-receiver.html)
+!!! note
+    To setup your alert receiver, with Amazon SNS, follow [this documentation](https://docs.aws.amazon.com/prometheus/latest/userguide/AMP-alertmanager-receiver.html)
 
 
 ## Deploy an Example Java Application
@@ -178,9 +178,10 @@ tomcat-traffic-generator          1/1     Running             0          11s
 If you leave this stack running, you will continue to incur charges. To remove all resources
 created by Terraform, [refresh your Grafana API key](#6-grafana-api-key) and run the command below.
 
-Be careful, this command will removing everything created by Terraform. If you wish
-to keep your Amazon Managed Grafana or Amazon Managed Service for Prometheus workspaces. Remove them
-from your terraform state before running the destroy command.
+!!! warning
+    Be careful, this command will removing everything created by Terraform. If you wish
+    to keep your Amazon Managed Grafana or Amazon Managed Service for Prometheus workspaces. Remove them
+    from your terraform state before running the destroy command.
 
 ```bash
 terraform destroy