Proper call-outs; minor fixes

Mirantis · Oct 14, 2024 · 14b6bdf · 14b6bdf
1 parent 7947229
commit 14b6bdf
Show file tree

Hide file tree

Showing 12 changed files with 55 additions and 32 deletions.
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -1,4 +1,4 @@
-name: docs 
+name: docs
 on:
   push:
     branches:
@@ -17,7 +17,7 @@ jobs:
       - uses: actions/setup-python@v5
         with:
           python-version: 3.x
-      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV 
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
       - uses: actions/cache@v4
         with:
           key: mkdocs-material-${{ env.cache_id }}
@@ -26,5 +26,6 @@ jobs:
             mkdocs-material-
       - run: pip install \
               mkdocs-material \
+              markdown-callouts \
               mkdocs-mermaid2-plugin
-      - run: mkdocs gh-deploy --force
+      - run: mkdocs gh-deploy --force
diff --git a/docs/aws/cloudformation.md b/docs/aws/cloudformation.md
@@ -2,7 +2,8 @@
 
 Before launching a cluster on AWS, it's crucial to set up your AWS infrastructure provider:
 
-> Note. Skip steps below if you've already configured IAM policy for your account
+> NOTE:
+> Skip steps below if you've already configured IAM policy for your account
 
 1. In order to use clusterawsadm you must have an administrative user in an AWS account. Once you have that
    administrator user you need to set your environment variables:

diff --git a/docs/aws/cluster-parameters.md b/docs/aws/cluster-parameters.md
@@ -39,7 +39,7 @@ stringData:
   SecretAccessKey: "++AQDEXAMPLE"
 ```
 
-> [!NOTE]
+> NOTE:
 > The secret must be created in the same `Namespace` where CAPA provider is
 > running. In case of Project 2A it's currently `hmc-system`. Placing secret in
 > any other `Namespace` will result controller not able to read it.

diff --git a/docs/aws/hosted-control-plane.md b/docs/aws/hosted-control-plane.md
@@ -82,7 +82,7 @@ With all the collected data your `ManagedCluster` manifest will look similar to
           - sg-0e000000000000000
 ```
 
-> [!NOTE]
+> NOTE:
 > In this example we're using the `us-west-1` region, but you should use the region of your VPC.
 
 ## HMC ManagedCluster manifest generation

diff --git a/docs/azure/cluster-parameters.md b/docs/azure/cluster-parameters.md
@@ -34,7 +34,8 @@ will look like this:
 }
 ```
 
-*Note: make sure to save this credentials and treat them like passwords.*
+> NOTE:
+> Make sure to save this credentials and treat them like passwords.
 
 With the data from the json you can now create the `AzureClusterIdentity` object
 and it's secret.

diff --git a/docs/azure/hosted-control-plane.md b/docs/azure/hosted-control-plane.md
@@ -158,5 +158,6 @@ placed to finish cluster deletion.
 In case if have orphaned `AzureMachines` left you have to delete finalizers on
 them manually after making sure that no VMs are present in Azure.
 
-*Note: since Azure admission prohibits orphaned objects mutation you'll have to
-disable it by deleting it's `mutatingwebhookconfiguration`*
+> NOTE:
+> Since Azure admission prohibits orphaned objects mutation you'll have to disable
+> it by deleting it's `mutatingwebhookconfiguration`*
diff --git a/docs/credential/main.md b/docs/credential/main.md
@@ -7,8 +7,8 @@ should be passed to it. The following describes how it is implemented in 2A.
 
 The following is the process of passing credentials to the system:
 
-1. Provider specific `ClusterIdentity` and `Secret` is created
-2. `Credential` object is created referencing `ClusterIdentity` from step 1.
+1. Provider specific `ClusterIdentity` and `Secret` are created
+2. `Credential` object is created referencing `ClusterIdentity` from step **1**.
 3. The `Credential` object is then referenced in the `ManagedCluster`.
 
 By design steps 1 and 2 should be executed by the platform lead engender who has
@@ -18,10 +18,10 @@ like `ClusterIndentity`.
 
 ## Credential object
 
-The `Credential` object acts like a reference to the underlying credentials. It is
-namespace-scoped, which means that it must be in the same `Namespace` with the
-`ManagedCluster` it is referenced in.
-Actual credentials can be located in any namespace.
+The `Credential` object acts like a reference to the underlying credentials. It
+is namespace-scoped, which means that it must be in the same `Namespace` with
+the `ManagedCluster` it is referenced in. Actual credentials can be located in
+any namespace.
 
 ### Example
 

diff --git a/docs/dev.md b/docs/dev.md
@@ -93,7 +93,7 @@ export KUBECONFIG=~/.kube/config
 ./bin/clusterctl describe cluster <managedcluster-name> -n hmc-system --show-conditions all
 ```
 
-> [!NOTE]
+> NOTE:
 > If you encounter any errors in the output of `clusterctl describe cluster` inspect the logs of the
 > `capa-controller-manager` with:
 > ```

diff --git a/docs/install/installation.md b/docs/install/installation.md
@@ -1,8 +1,10 @@
 ### Installation
 
-```
+```bash
 export KUBECONFIG=<path-to-management-kubeconfig>
+```
 
+```bash
 helm install hmc oci://ghcr.io/mirantis/hmc/charts/hmc --version <hmc-version> -n hmc-system --create-namespace
 ```
 
@@ -64,13 +66,14 @@ export KUBECONFIG=<path-to-management-kubeconfig>
 kubectl get template -n hmc-system -o go-template='{{ range .items }}{{ if eq .status.type "deployment" }}{{ .metadata.name }}{{ printf "\n" }}{{ end }}{{ end }}'
 ```
 
-For details about the `Template system` in HMC, see [Templates system](../template/main.md). 
+For details about the `Template system` in HMC, see [Templates system](../template/main.md).
 
 If you want to deploy hostded control plate template, make sure to check additional notes on [Hosted control plane](../aws/hosted-control-plane.md).
 
 2. Create the file with the `ManagedCluster` configuration:
 
-> Substitute the parameters enclosed in angle brackets with the corresponding values.\
+> NOTE:
+> Substitute the parameters enclosed in angle brackets with the corresponding values.
 > Enable the `dryRun` flag if required. For details, see [Dry run](#dry-run).
 
 ```yaml
@@ -92,13 +95,14 @@ spec:
 
 4. Check the status of the newly created `ManagedCluster` object:
 
-`kubectl -n <managedcluster-namespace> get managedcluster <managedcluster-name> -o=yaml`
+`kubectl -n <managedcluster-namespace> get managedcluster.hmc <managedcluster-name> -o=yaml`
 
 5. Wait for infrastructure to be provisioned and the cluster to be deployed (the provisioning starts only when
 `spec.dryRun` is disabled):
 
    `kubectl -n <managedcluster-namespace> get cluster <managedcluster-name> -o=yaml`
 
+> TIP:
 > You may also watch the process with the `clusterctl describe` command (requires the `clusterctl` CLI to be installed):
 > ```
 > clusterctl describe cluster <managedcluster-name> -n <managedcluster-namespace> --show-conditions all
@@ -200,10 +204,11 @@ spec:
 ## Cleanup
 
 1. Remove the Management object:
-  
+
 `kubectl delete management.hmc hmc`
 
-> Note: make sure you have no HMC ManagedCluster objects left in the cluster prior to Management deletion
+> NOTE:
+> Make sure you have no HMC ManagedCluster objects left in the cluster prior to Management deletion
 
 2. Remove the `hmc` Helm release:
 

diff --git a/docs/install/quick-start.md b/docs/install/quick-start.md
@@ -1,11 +1,17 @@
 
-## TLDR
+## TL;DR
 
-    kubectl apply -f https://github.com/Mirantis/hmc/releases/download/v0.0.1/install.yaml
+```bash
+kubectl apply -f https://github.com/Mirantis/hmc/releases/download/v0.0.1/install.yaml
+```
 
 or install using `helm`
 
-    helm install hmc oci://ghcr.io/mirantis/hmc/charts/hmc --version v0.0.1 -n hmc-system --create-namespace
+```bash
+helm install hmc oci://ghcr.io/mirantis/hmc/charts/hmc --version v0.0.1 -n hmc-system --create-namespace
+```
 
-> Note: The HMC installation using Kubernetes manifests does not allow customization of the deployment.
-> If the custom HMC configuration should be applied, install HMC using the Helm chart.
+> NOTE:
+> The HMC installation using Kubernetes manifests does not allow customization of
+> the deployment. If the custom HMC configuration should be applied, install HMC
+> using the Helm chart.
diff --git a/docs/mk-docs-setup.md b/docs/mk-docs-setup.md
@@ -12,7 +12,7 @@
 
 ## Setting up MKdocs and dependancies
 
-1. Setup python Virtual Environment 
+1. Setup python Virtual Environment
 
     `python3  -m venv ./mkdocs`
     `source ./mkdocs/bin/activate`
@@ -27,6 +27,8 @@
 
     `pip install mkdocs-material`
 
+	`pip install markdown-callouts`
+
 ## Run MKdocs for dev
 
 * `mkdocs serve` - Start the live-reloading docs server.
@@ -39,4 +41,3 @@ For full documentation visit [mkdocs.org](https://www.mkdocs.org).
 * `mkdocs serve` - Start the live-reloading docs server.
 * `mkdocs build` - Build the documentation site.
 * `mkdocs -h` - Print help message and exit.
-
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -42,8 +42,7 @@ theme:
     - navigation.tabs.sticky
     - navigation.footer
     - navigation.path
-
-
+    - content.code.copy
 
 extra_css:
   - stylesheets/extra.css
@@ -57,19 +56,27 @@ plugins:
 
 # Page tree
 
+markdown_extensions:
+  - callouts
+  - pymdownx.details
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
 nav:
   - Home: index.md
   - Introduction: introduction.md
   - Installation:
       - Quick Start: install/quick-start.md
       - Installation Guide: install/installation.md
       - Templates: template/main.md
+      - Credential System: credential/main.md
   - Developer Guide: dev.md
   - Provider Guides:
     - AWS: 
       - aws/main.md
       - aws/cloudformation.md
-      - aws/credentials.md
       - aws/cluster-parameters.md
       - aws/hosted-control-plane.md
       - aws/nuke.md