Updates for how to make changes, and where to view the deployments (#208

)

.github/workflows/closed_pr.yaml

@@ -7,6 +7,6 @@ on:
 
 jobs:
   push:
-    uses: stakater/.github/.github/workflows/[email protected].103
+    uses: stakater/.github/.github/workflows/[email protected].105
     secrets:
       GH_TOKEN: ${{ secrets.PUBLISH_TOKEN }}

.github/workflows/delete_branch.yaml

@@ -4,7 +4,7 @@ on: delete
 
 jobs:
   delete:
-    uses: stakater/.github/.github/workflows/[email protected].103
+    uses: stakater/.github/.github/workflows/[email protected].105
     with:
       LATEST_DOC_VERSION: "1.0"
     secrets:

.github/workflows/pull_request.yaml

@@ -4,23 +4,23 @@ on:
   pull_request:
     branches:
       - "main"
-      - "[0-9]+.[0-9]+"
+      - "^[0-9]+.[0-9]+$"
 
 jobs:
   doc_qa:
-    uses: stakater/.github/.github/workflows/[email protected].103
+    uses: stakater/.github/.github/workflows/[email protected].105
     with:
       MD_CONFIG: .github/md_config.json
       DOC_SRC: content README.md
       MD_LINT_CONFIG: .markdownlint.yaml
   deploy_doc:
-    uses: stakater/.github/.github/workflows/[email protected].103
+    uses: stakater/.github/.github/workflows/[email protected].105
     secrets:
       GH_TOKEN: ${{ secrets.PUBLISH_TOKEN }}
   build_container:
     needs: deploy_doc
     if: ${{ github.base_ref == 'main' }}
-    uses: stakater/.github/.github/workflows/[email protected].103
+    uses: stakater/.github/.github/workflows/[email protected].105
     with:
       DOCKER_BUILD_CONTEXTS: content=https://github.com/stakater/mto-docs.git#pull-request-deployments
       DOCKER_FILE_PATH: Dockerfile

.github/workflows/push.yaml

@@ -4,11 +4,11 @@ on:
   push:
     branches:
       - "main"
-      - "[0-9]+.[0-9]+"
+      - "^[0-9]+.[0-9]+$"
 
 jobs:
   push:
-    uses: stakater/.github/.github/workflows/[email protected].103
+    uses: stakater/.github/.github/workflows/[email protected].105
     with:
       LATEST_DOC_VERSION: "1.0"
     secrets:

.github/workflows/release.yaml

@@ -7,11 +7,11 @@ on:
 
 jobs:
   create_release:
-    uses: stakater/.github/.github/workflows/[email protected].103
+    uses: stakater/.github/.github/workflows/[email protected].105
     secrets:
       SLACK_WEBHOOK_URL: ${{ secrets.STAKATER_DELIVERY_SLACK_WEBHOOK }}
   build_container:
-    uses: stakater/.github/.github/workflows/[email protected].103
+    uses: stakater/.github/.github/workflows/[email protected].105
     with:
       DOCKER_BUILD_CONTEXTS: content=https://github.com/stakater/mto-docs.git#gh-pages
       DOCKER_FILE_PATH: Dockerfile

README.md

@@ -2,25 +2,30 @@
 
 This repository contains the source for the documentation for [Multi Tenant Operator](https://www.stakater.com/mto). It is built using [MkDocs](https://github.com/mkdocs/mkdocs) which is based on Python. It is also versioned using [mike](https://github.com/jimporter/mike).
 
-## Latest doc version
-
-Before deploying or deleting a version, make sure to specify the correct latest version in the workflow files.
-
-Make sure the latest doc version is also specified in the versioned branches.
-
 ## GitHub Actions
 
 This repository has [GitHub action workflow](./.github/workflows/) which checks the quality of the documentation and builds the [`Dockerfile`](./Dockerfile) image on Pull Requests. On a push to the `main` branch, it will create a GitHub release and push the built image to an image repository.
 
 ## How to make changes
 
-Fork the repository and make a pull request.
+1. Fork the repository
+1. Make a pull request
+1. Workflow will run QA checks, make sure all jobs have succeeded before requesting a review
+1. Pull requests builds are published for review on `https://stakater.github.io/mto-docs/<branch-name>/`
+1. On merge of a pull request, the documentation is published on [`docs.stakater.com/mto/`](https://docs.stakater.com/mto/)
 
-For MkDocs overrides, it is important to know that you should only make changes in the [`theme_override`](./theme_override/) and the [`content`](./content/) directory. Also, be mindful of only changing the [`theme_override/mkdocs.yml`](./theme_override/mkdocs.yml) file since there are more than one such file.
+> [!NOTE]
+> For MkDocs overrides, it is important to know that you should only make changes in the [`theme_override`](./theme_override/) and the [`content`](./content/) directory.
+>
+> Be mindful of only changing the [`theme_override/mkdocs.yml`](./theme_override/mkdocs.yml) file since there are more than one such file.
+>
+> Before deploying or deleting a version, make sure to specify the correct latest version in the workflow files.
+>
+> Make sure the latest doc version is also specified in the versioned branches.
 
-## Take update on git submodule
+### Update git submodule
 
-This project contains a git submodule and if you wish to take an update on it, you can use this command:
+This project contains a git submodule and if you need to update it, use this command:
 
 ```bash
 git submodule update --init --recursive --remote
@@ -90,7 +95,7 @@ brew install markdownlint-cli
 markdownlint -c .markdownlint.yaml content
 ```
 
-Spell checking:
+To run spell checking:
 
 ```bash
 brew install vale

content/installation/managed-kubernetes/azure-aks.md

@@ -116,15 +116,15 @@ az role assignment create --assignee $OPSSRE_ID --role "Azure Kubernetes Service
 
 ### Create test users in `Entra ID`
 
-Set User Principal Name (UPN) and password for your users. The UPN must include the verified domain name of your tenant, for example [email protected].
+Set User Principal Name (UPN) and password for your users. The UPN must include the verified domain name of your tenant, for example `[email protected]`.
 
-Following command reads the UPN for the appdev group and stores it in the AAD_DEV_UPN variable:
+Following command reads the UPN for the appdev group and stores it in the `AAD_DEV_UPN` variable:
 
 ```terminal
 echo "Please enter the UPN for application developers: " && read AAD_DEV_UPN
 ```
 
-For this scope of this blog, we will assume that the entered UPN was [email protected].
+For this scope of this blog, we will assume that the entered UPN was `[email protected]`.
 
 Following command reads the password for your user and stores it in the AAD_DEV_PW variable:
 
@@ -146,13 +146,13 @@ az ad group member add --group appdev --member-id $AKSDEV_ID
 
 Repeat the steps for `OPS SRE` user.
 
-The following command reads the UPN for your user and stores it in the AAD_SRE_UPN variable:
+The following command reads the UPN for your user and stores it in the `AAD_SRE_UPN` variable:
 
 ```terminal
 echo "Please enter the UPN for SREs: " && read AAD_SRE_UPN
 ```
 
-For this scope of this blog, we will assume that the entered UPN was [email protected].
+For this scope of this blog, we will assume that the entered UPN was `[email protected]`.
 
 The following command reads the password for your user and stores it in the AAD_SRE_PW variable: