feat: Add documentation site

Signed-off-by: Chris Butler <[email protected]>
opendatahub-io-contrib · Mar 17, 2024 · 8156090 · 8156090
1 parent 85a7996
commit 8156090
Show file tree

Hide file tree

Showing 17 changed files with 369 additions and 155 deletions.
diff --git a/.github/workflows/deploy-documentation.yml b/.github/workflows/deploy-documentation.yml
@@ -0,0 +1,21 @@
+name: Deploy documentation
+on:
+  push:
+    branches:
+    - main
+  workflow_dispatch:
+permissions:
+  contents: write
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+    - uses: actions/setup-python@v4
+      with:
+        python-version: 3.x
+    - run: pip install -r requirements.txt
+    - run: sudo apt-get -y install libcairo2-dev libfreetype6-dev libffi-dev libjpeg-dev libpng-dev libz-dev
+    - run: mkdocs gh-deploy
diff --git a/.github/workflows/validate-documentation.yml b/.github/workflows/validate-documentation.yml
@@ -0,0 +1,25 @@
+name: ci
+on:
+  pull_request:
+    branches:
+    - main
+  workflow_dispatch:
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+    - uses: actions/setup-python@v4
+      with:
+        python-version: 3.x
+    - run: pip install -r requirements.txt
+    - run: pre-commit install
+    - run: pre-commit run --all-files
+    - name: git diff
+      if: always()
+      run: git diff
+
+    - run: sudo apt-get -y install libcairo2-dev libfreetype6-dev libffi-dev libjpeg-dev libpng-dev libz-dev
+    - run: mkdocs build -c -s
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -0,0 +1,21 @@
+repos:
+- repo: https://github.com/pre-commit/pre-commit-hooks
+  rev: v4.5.0 # Use the ref you want to point at
+  hooks:
+  - id: check-merge-conflict
+  - id: check-case-conflict
+  # - id: check-yaml
+  #   args: ['--unsafe']
+  - id: no-commit-to-branch
+    args: [--branch, main]
+- repo: https://github.com/executablebooks/mdformat
+  rev: 0.7.17
+  exclude: "common/letsencrypt/README.md"
+  hooks:
+  - id: mdformat
+    additional_dependencies:
+    - mdformat-tables
+    - mdformat-config
+    - mdformat-frontmatter
+    - mdformat-gfm
+    - mdformat-admon
diff --git a/README.md b/README.md
@@ -3,20 +3,21 @@
 Today a dominant usecase for deploying Large Language Models (LLMs) within the enteprise is as a enterprise search assistant. LLMs without any underlying context a prone to halucination. Retrieval Augmented Generation (RAG) is an architecture where the LLM is pared with a vector database. The vector database contains a specialised index of enterprise documents which provide 'context' to the LLM allowing more accurate results AND allowing employees to follow up with source documents. This project is a reference pattern for deploying a RAG search assistant built on top of Red Hat OpenShift AI.
 
 ## Validated patterns deployment.
-This project uses [validated patterns](https://validatedpatterns.io/) to allow this project to be consistently deployed across multiple platforms. The project itself has been forked off of the core [mutlicloud-gitops pattern](github.com/validatedpatterns/multicloud-gitops/).
 
+This project uses [validated patterns](https://validatedpatterns.io/) to allow this project to be consistently deployed across multiple platforms. The project itself has been forked off of the core [mutlicloud-gitops pattern](github.com/validatedpatterns/multicloud-gitops/).
 
 The current pattern for Red Hat OpenShift AI makes the following assumptions:
+
 1. Single cluster deployment
-2. 
+1.
 
 Validated patterns currently includes significant boilerplate which will be stripped out over time.
 
-
 ## Deploying and assumption
+
 The deployment method for validated pattenrs is [described here](https://validatedpatterns.io/patterns/multicloud-gitops/mcg-getting-started/).
 
 1. An OpenShift Cluster with
    1. Cluster admin rights logged in with `oc` where the repo is cloned out
-   2. Connectivity through to github (or an equivalent git platform)
-   3. GPUs on at least one node within the cluster.
+   1. Connectivity through to github (or an equivalent git platform)
+   1. GPUs on at least one node within the cluster.
diff --git a/common/Changes.md b/common/Changes.md
@@ -2,111 +2,111 @@
 
 ## Sep 25, 2023
 
-* Upgraded ESO to v0.9.5
+- Upgraded ESO to v0.9.5
 
 ## Aug 17, 2023
 
-* Introduced support for multisource applications via .chart + .chartVersion
+- Introduced support for multisource applications via .chart + .chartVersion
 
 ## Jul 8, 2023
 
-* Introduced a default of 20 for sync failures retries in argo applications (global override via global.options.applicationRetryLimit
+- Introduced a default of 20 for sync failures retries in argo applications (global override via global.options.applicationRetryLimit
   and per-app override via .syncPolicy)
 
 ## May 22, 2023
 
-* Upgraded ESO to 0.8.2
-* *Important* we now use the newly blessed sso config for argo. This means that gitops < 1.8 are *unsupported*
+- Upgraded ESO to 0.8.2
+- *Important* we now use the newly blessed sso config for argo. This means that gitops \< 1.8 are *unsupported*
 
 ## May 18, 2023
 
-* Introduce a EXTRA_HELM_OPTS env variable that will be passed to the helm invocations
+- Introduce a EXTRA_HELM_OPTS env variable that will be passed to the helm invocations
 
 ## April 21, 2023
 
-* Added labels and annotation support to namespaces.yaml template
+- Added labels and annotation support to namespaces.yaml template
 
 ## Apr 11, 2023
 
-* Apply the ACM ocp-gitops-policy everywhere but the hub
+- Apply the ACM ocp-gitops-policy everywhere but the hub
 
 ## Apr 7, 2023
 
-* Moved to gitops-1.8 channel by default (stable is unmaintained and will be dropped starting with ocp-4.13)
+- Moved to gitops-1.8 channel by default (stable is unmaintained and will be dropped starting with ocp-4.13)
 
 ## March 20, 2023
 
-* Upgraded ESO to 0.8.1
+- Upgraded ESO to 0.8.1
 
 ## February 9, 2023
 
-* Add support for /values-<platform>.yaml and for /values-<platform>-<clusterversion>.yaml
+- Add support for /values-<platform>.yaml and for /values-<platform>-<clusterversion>.yaml
 
 ## January 29, 2023
 
-* Stop extracting the HUB's CA via an imperative job running on the imported cluster.
+- Stop extracting the HUB's CA via an imperative job running on the imported cluster.
   Just use ACM to push the HUB's CA out to the managed clusters.
 
 ## January 23, 2023
 
-* Add initial support for running ESO on ACM-imported clusters
+- Add initial support for running ESO on ACM-imported clusters
 
 ## January 18, 2023
 
-* Add validate-schema target
+- Add validate-schema target
 
 ## January 13, 2023
 
-* Simplify the secrets paths when using argo hosted sites
+- Simplify the secrets paths when using argo hosted sites
 
 ## January 10, 2023
 
-* vaultPrefixes is now optional in the v2 secret spec and defaults to ["hub"]
+- vaultPrefixes is now optional in the v2 secret spec and defaults to \["hub"\]
 
 ## December 9, 2022
 
-* Dropped insecureUnsealVaultInsideCluster (and file_unseal) entirely. Now
+- Dropped insecureUnsealVaultInsideCluster (and file_unseal) entirely. Now
   vault is always unsealed via a cronjob in the cluster. It is recommended to
   store the imperative/vaultkeys secret offline securely and then delete it.
 
 ## December 8, 2022
 
-* Removed the legacy installation targets:
+- Removed the legacy installation targets:
   `deploy upgrade legacy-deploy legacy-upgrade`
   Patterns must now use the operator-based installation
 
 ## November 29, 2022
 
-* Upgraded vault-helm to 0.23.0
-* Enable vault-ssl by default
+- Upgraded vault-helm to 0.23.0
+- Enable vault-ssl by default
 
 ## November 22, 2022
 
-* Implemented a new format for the values-secret.yaml. Example can be found in examples/ folder
-* Now the order of values-secret file lookup is the following:
+- Implemented a new format for the values-secret.yaml. Example can be found in examples/ folder
+- Now the order of values-secret file lookup is the following:
   1. ~/values-secret-<patternname>.yaml
-  2. ~/values-secret.yaml
-  3. <patterngitrepo>/values-secret.yaml.template
-* Add support for ansible vault encrypted values-secret files. You can now encrypt your values-secret file
+  1. ~/values-secret.yaml
+  1. <patterngitrepo>/values-secret.yaml.template
+- Add support for ansible vault encrypted values-secret files. You can now encrypt your values-secret file
   at rest with `ansible-vault encrypt ~/values-secret.yaml`. When running `make load-secrets` if an encrypted
   file is encountered the user will be prompted automatically for the password to decrypt it.
 
 ## November 6, 2022
 
-* Add support for /values-<CloudPlatform>-<clusterGroup>.yaml (e.g. /values-AWS-group-one.yaml)
+- Add support for /values-<CloudPlatform>-<clusterGroup>.yaml (e.g. /values-AWS-group-one.yaml)
 
 ## October 28, 2022
 
-* Updated vault helm chart to v0.22.1 and vault containers to 1.12.0
+- Updated vault helm chart to v0.22.1 and vault containers to 1.12.0
 
 ## October 25, 2022
 
-* Updated External Secrets Operator to v0.6.0
-* Moved to -UBI based ESO containers
+- Updated External Secrets Operator to v0.6.0
+- Moved to -UBI based ESO containers
 
 ## October 13, 2022
 
-* Added global.clusterVersion as a new helm variable which represents the OCP
+- Added global.clusterVersion as a new helm variable which represents the OCP
   Major.Minor cluster version. By default now a user can add a
   values-<ocpversion>-<clustergroup>.yaml file to have specific cluster version
   overrides (e.g. values-4.10-hub.yaml). Will need Validated Patterns Operator >= 0.0.6
@@ -115,31 +115,36 @@
 
 ## October 4, 2022
 
-* Extended the values-secret.yaml file to support multiple vault paths and re-wrote
+- Extended the values-secret.yaml file to support multiple vault paths and re-wrote
   the push_secrets feature as python module plugin. This requires the following line
-  in a pattern's ansible.cfg's '[defaults]' stanza:
+  in a pattern's ansible.cfg's '\[defaults\]' stanza:
 
   `library=~/.ansible/plugins/modules:./ansible/plugins/modules:./common/ansible/plugins/modules:/usr/share/ansible/plugins/modules`
 
 ## October 3, 2022
 
-* Restore the ability to install a non-default site: `make TARGET_SITE=mysite install`
-* Revised tests (new output and filenames, requires adding new result files to git)
-* ACM 2.6 required for ACM-based managed sites
-* Introduced global.clusterDomain template variable (without the `apps.` prefix)
-* Removed the ability to send specific charts to another cluster, use hosted argo sites instead
-* Added the ability to have the hub host `values-{site}.yaml` for spoke clusters.
+- Restore the ability to install a non-default site: `make TARGET_SITE=mysite install`
+
+- Revised tests (new output and filenames, requires adding new result files to git)
+
+- ACM 2.6 required for ACM-based managed sites
+
+- Introduced global.clusterDomain template variable (without the `apps.` prefix)
+
+- Removed the ability to send specific charts to another cluster, use hosted argo sites instead
+
+- Added the ability to have the hub host `values-{site}.yaml` for spoke clusters.
 
   The following example would deploy the namespaces, subscriptions, and
   applications defined in `values-group-one.yaml` to the `perth` cluster
   directly from ArgoCD on the hub.
 
   ```yaml
   managedClusterGroups:
-  - name: group-one
-    hostedArgoSites:
-    - name: perth
-      domain: perth1.beekhof.net
-      bearerKeyPath: secret/data/hub/cluster_perth
-      caKeyPath: secret/data/hub/cluster_perth_ca
+    - name: group-one
+      hostedArgoSites:
+        - name: perth
+          domain: perth1.beekhof.net
+          bearerKeyPath: secret/data/hub/cluster_perth
+          caKeyPath: secret/data/hub/cluster_perth_ca
   ```
diff --git a/common/ansible/roles/iib_ci/README.md b/common/ansible/roles/iib_ci/README.md
@@ -61,23 +61,23 @@ make EXTRA_HELM_OPTS="--set main.extraParameters[0].name=clusterGroup.subscripti
 Since 4.13 supports an internal registry that can cope with v2 docker manifests, we
 use that. Run `make iib` with the following environment variables set:
 
-* `INDEX_IMAGES=registry-proxy.engineering.redhat.com/rh-osbs/iib:492329`
-* `KUBEADMINPASS="11111-22222-33333-44444"`
+- `INDEX_IMAGES=registry-proxy.engineering.redhat.com/rh-osbs/iib:492329`
+- `KUBEADMINPASS="11111-22222-33333-44444"`
 
 ### OCP 4.12 and previous versions
 
 Due to the lack of v2 manifest support on the internal registry, we use an external
 registry. Run `make iib` with the following environment variables set:
 
-* `INDEX_IMAGES=registry-proxy.engineering.redhat.com/rh-osbs/iib:492329`
-* `REGISTRY=quay.io/rhn_support_mbaldess/iib`
-* `REGISTRY_TOKEN=<username>:<token>`
+- `INDEX_IMAGES=registry-proxy.engineering.redhat.com/rh-osbs/iib:492329`
+- `REGISTRY=quay.io/rhn_support_mbaldess/iib`
+- `REGISTRY_TOKEN=<username>:<token>`
 
 *Note*: For the REGISTRY_TOKEN go to your quay repository, add a robot with "Write" permissions. The robot created will have a "username" and "password" fields. Set the REGISTRY_TOKEN environment variable to that value.
 
 ## Useful commands
 
-* List IIBs for an operator:
+- List IIBs for an operator:
 
 ```sh
 ansible-playbook common/ansible/playbooks/iib-ci/lookup.yml
@@ -90,7 +90,7 @@ ok: [localhost] => (item=v4.13) => {
 
 Override the `operator` value with the desired bundle name to figure out the last IIBs for it.
 
-* List all images uploaded to the internal registry:
+- List all images uploaded to the internal registry:
 
 ```sh
 oc exec -it -n openshift-image-registry $(oc get pods -n openshift-image-registry -o json | jq -r '.items[].metadata.name | select(. | test("^image-registry-"))' | head -n1) -- bash -c "curl -k -u kubeadmin:$(oc whoami -t) https://localhost:5000/v2/_catalog"