Adding stakater-docs-mkdocs-theme submodule to mto-docs (#97)

Co-authored-by: Fateh Ullah <[email protected]>

.github/workflows/closed_pr.yaml

@@ -7,6 +7,6 @@ on:
 
 jobs:
   push:
-    uses: stakater/.github/.github/workflows/pull_request_closed[email protected].54
+    uses: stakater/.github/.github/workflows/mkdocs_pull_request_closed[email protected].60
     secrets:
-      GH_TOKEN: ${{ secrets.STAKATER_GITHUB_TOKEN }}
+      GH_TOKEN: ${{ secrets.STAKATER_GITHUB_TOKEN }}

.github/workflows/delete_branch.yaml

@@ -5,6 +5,7 @@ on:
 
 jobs:
   delete:
-    uses: stakater/.github/.github/workflows/branch_deleted[email protected].54
+    uses: stakater/.github/.github/workflows/mkdocs_branch_deleted[email protected].60
     secrets:
       GH_TOKEN: ${{ secrets.STAKATER_GITHUB_TOKEN }}
+

.github/workflows/pull_request.yaml

@@ -8,14 +8,14 @@ on:
 
 jobs:
   doc_qa:
-    uses: stakater/.github/.github/workflows/[email protected].54
+    uses: stakater/.github/.github/workflows/[email protected].60
     with:
       MD_CONFIG: .github/md_config.json
       DOC_SRC: content
       MD_LINT_CONFIG: .markdownlint.yaml
   build_container:
     if: ${{ github.base_ref == 'main' }}
-    uses: stakater/.github/.github/workflows/[email protected].54
+    uses: stakater/.github/.github/workflows/[email protected].60
     with:
       DOCKER_BUILD_CONTEXTS: content=https://github.com/stakater/mto-docs.git#pull-request-deployments
       DOCKER_FILE_PATH: Dockerfile
@@ -26,6 +26,6 @@ jobs:
       SLACK_WEBHOOK_URL: ${{ secrets.STAKATER_DELIVERY_SLACK_WEBHOOK }}
       DOCKER_SECRETS: GIT_AUTH_TOKEN=${{ secrets.STAKATER_GITHUB_TOKEN }}
   deploy_doc:
-    uses: stakater/.github/.github/workflows/pull_request_versioned_doc[email protected].54
+    uses: stakater/.github/.github/workflows/mkdocs_pull_request_versioned_doc[email protected].60
     secrets:
       GH_TOKEN: ${{ secrets.STAKATER_GITHUB_TOKEN }}

.github/workflows/push.yaml

@@ -8,6 +8,6 @@ on:
 
 jobs:
   push:
-    uses: stakater/.github/.github/workflows/push_versioned_doc[email protected].54
+    uses: stakater/.github/.github/workflows/mkdocs_push_versioned_doc[email protected].60
     secrets:
       GH_TOKEN: ${{ secrets.STAKATER_GITHUB_TOKEN }}

.github/workflows/release.yaml

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

.gitignore

@@ -1,5 +1,6 @@
 # Dist files
 dist/
+site/
 lib/
 
 # Test temp files
@@ -22,4 +23,6 @@ node_modules
 site/
 
 
-.idea
+.idea
+
+mkdocs.yml

.gitmodules

@@ -1,3 +1,3 @@
-[submodule "vocabulary"]
-	path = vocabulary
-	url = git@github.com:stakater/vocabulary.git
+[submodule "theme_common"]
+	path = theme_common
+	url = https://github.com/stakater/stakater-docs-mkdocs-theme.git

.vale.ini

@@ -1,4 +1,4 @@
-StylesPath = "vocabulary/styles"
+StylesPath = "theme_common/vocabulary/styles"
 MinAlertLevel = warning
 
 Vocab = "Stakater"

Dockerfile

@@ -18,4 +18,4 @@ LABEL name="Multi Tenant Operator Documentation" \
 
 EXPOSE 8080:8080/tcp
 
-CMD ["nginx", "-g", "daemon off;"]
+CMD ["nginx", "-g", "daemon off;"]

DockerfileLocal

@@ -0,0 +1,44 @@
+
+FROM python:3.12-alpine as builder
+
+# set workdir
+RUN mkdir -p $HOME/application
+WORKDIR $HOME/application
+
+# copy the entire application
+COPY --chown=1001:root . .
+
+RUN pip install -r theme_common/requirements.txt
+
+# In case you have your own python dependencies, you can use activate below command:
+# RUN pip install -r requirements.txt
+
+# pre-mkbuild step, we are infusing common and local theme changes
+RUN python theme_common/scripts/combine_theme_resources.py theme_common/resources theme_override/resources dist/_theme
+RUN python theme_common/scripts/combine_mkdocs_config_yaml.py theme_common/mkdocs.yml theme_override/mkdocs.yml mkdocs.yml
+
+RUN rm -f 'prepare_theme.sh' && \
+    rm -rf theme_global && \
+    rm -rf theme_common
+
+# build the docs
+RUN mkdocs build
+# remove the build theme because it is not needed after site is build.
+RUN rm -rf dist
+
+FROM nginxinc/nginx-unprivileged:1.25-alpine as deploy
+COPY --from=builder $HOME/application/site/ /usr/share/nginx/html/
+COPY default.conf /etc/nginx/conf.d/
+
+# set non-root user
+USER 1001
+
+LABEL name="Multi Tenant Operator Documentation" \
+      maintainer="Stakater <[email protected]>" \
+      vendor="Stakater" \
+      release="1" \
+      summary="Documentation for Multi Tenant Operator"
+
+EXPOSE 8080:8080/tcp
+
+CMD ["nginx", "-g", "daemon off;"]

README.md

@@ -1,3 +1,104 @@
 # Multi Tenant Operator Documentation
 
 Documentation for [Multi Tenant Operator](https://www.stakater.com/mto)
+
+
+SAAP docs are built using [MkDocs](https://github.com/mkdocs/mkdocs) which is based on Python.
+
+## GitHub Actions
+
+This repository has GitHub action workflow which checks the quality of the documentation and builds the Dockerfile image on Pull Requests. On a push to the main branch, it will create a GitHub release and push the built Dockerfile image to an image repository.
+
+## How to make changes
+It is important to know that you should only make changes in `theme_override` and `content` directory. Also, be mindful of which `mkdocs.yml` file you change since there are more than one such files.
+
+
+## Take update on git submodule
+
+This project contains a git submodule and if you wish to take an update on it, you can use this command:
+
+```bash
+git submodule update --init --recursive --remote
+```
+
+view `.gitmodules` file to see linked git submodules.
+
+## Build locally
+
+There are at least three options to get fast continuous feedback during local development:
+
+1. Build and run the docs using the Dockerfile image
+2. Run the commands locally
+
+### Build Dockerfile image and run container
+
+Build Dockerfile test image:
+
+```bash
+docker build . -t test -f Dockerfilelocal
+```
+
+Run test container:
+
+```bash
+docker run -p 8080:8080 test
+```
+
+Then access the docs on [`localhost:8080`](localhost:8080).
+
+### Run commands locally
+
+Use [virtualenvwrapper](https://virtualenvwrapper.readthedocs.io/en/latest/install.html) to set up Python virtual environment.
+
+Install [Python 3](https://www.python.org/downloads/).
+
+Install python environment dependencies if you are using any other than what is defined in `theme_common`.
+
+Then run below script to prepare theme from local and common theme resources. It will output to `dist/_theme` directory and create `mkdocs.yml` file in root directory. We are also installing the python dependencies coming from `theme_common` here.
+
+```bash
+$ ./prepare_theme.sh
+```
+
+Finally, serve the docs using the built-in web server which is based on Python http server - note that the production build will use Nginx instead:
+
+```bash
+$ mkdocs serve
+```
+
+or
+
+```bash
+$ python3 -m mkdocs serve
+```
+
+if you want to make theme changes with live reload, you can use `--watch-theme` with serve like below:
+```bash
+$ mkdocs serve --watch-theme
+```
+Then, you can make changes in `content` or `dist/_theme` folder. Please note that `dist/_theme` is a build folder and any changes made here will be lost if you do not move them to theme_common or theme_override folder.
+
+
+### QA Checks
+
+Markdown linting:
+
+```bash
+$ brew install markdownlint-cli
+$ markdownlint -c .markdownlint.yaml content
+```
+
+Spell checking:
+
+```bash
+$ brew install vale
+$ vale content
+```
+
+## Use Tilt
+
+Install [Tilt](https://docs.tilt.dev/index.html), then run:
+
+```bash
+$ tilt up
+```

content/faq.md

@@ -8,7 +8,7 @@
 unable to find annotation openshift.io/sa.scc.uid-range
 ```
 
-**Answer.** OpenShift recently updated its process of handling SCC, and it's now managed by annotations like `openshift.io/sa.scc.uid-range` on the namespaces. Absence  of them wont let pods schedule. The fix for the above error is to make sure ServiceAccount `system:serviceaccount:openshift-infra.` regex is always mentioned in `PrivilegedServiceAccounts` section of `IntegrationConfig`. This regex will allow operations from all `ServiceAccounts` present in `openshift-infra` namespace. More info at [Privileged Service Accounts](./integration-config.md#privileged-serviceaccounts)
+**Answer.** OpenShift recently updated its process of handling SCC, and it's now managed by annotations like `openshift.io/sa.scc.uid-range` on the namespaces. Absence  of them wont let pods schedule. The fix for the above error is to make sure ServiceAccount `system:serviceaccount:openshift-infra.` regex is always mentioned in `PrivilegedServiceAccounts` section of `IntegrationConfig`. This regex will allow operations from all `ServiceAccounts` present in `openshift-infra` namespace. More info at [Privileged Service Accounts](./how-to-guides/integration-config.md#privileged-serviceaccounts)
 
 ## Namespace Admission Webhook