feat: devhub

add workflow for devhub integration

.github/workflows/publish-devhub.yml

@@ -0,0 +1,67 @@
+name: Publish TechDocs
+
+on:
+  push:
+    branches: [wiki]
+    paths:
+      - "wiki/**"
+      - "mkdocs.yml"
+      - "catalog-info.yaml"
+jobs:
+  publish-techdocs-site:
+    runs-on: ubuntu-latest
+
+    env:
+      TECHDOCS_S3_BUCKET_NAME: ${{ secrets.TECHDOCS_S3_BUCKET_NAME }}
+      TECHDOCS_S3_DEV_ROOT_PATH: ${{ vars.TECHDOCS_S3_DEV_ROOT_PATH }}
+      AWS_ACCESS_KEY_ID: ${{ secrets.TECHDOCS_AWS_ACCESS_KEY_ID }}
+      AWS_SECRET_ACCESS_KEY: ${{ secrets.TECHDOCS_AWS_SECRET_ACCESS_KEY }}
+      AWS_REGION: ${{ secrets.TECHDOCS_AWS_REGION }}
+      AWS_ENDPOINT: ${{ secrets.TECHDOCS_AWS_ENDPOINT }}
+      ENTITY_NAMESPACE: ${{ vars.TECHDOCS_ENTITY_NAMESPACE }}
+      ENTITY_KIND: ${{ vars.TECHDOCS_ENTITY_KIND }}
+      ENTITY_NAME: ${{ vars.TECHDOCS_ENTITY_NAME }}
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v3
+
+      - uses: actions/setup-node@v3
+      - uses: actions/setup-python@v4
+        with:
+          python-version: '3.9'
+
+      - name: Install techdocs-cli
+        run: sudo npm install -g @techdocs/[email protected]
+
+      - name: Install mkdocs and mkdocs plugins
+        run: python -m pip install mkdocs-techdocs-core==1.*
+
+      - name: Generate docs site
+        run: techdocs-cli generate --no-docker --verbose
+
+      - name: Publish docs to dev bucket
+        # Always publish the docs to the dev bucket
+        # Dev is in the awsBucketRootPath
+        # Note: in  GitHub repo Settings -> Actions -> General under "fork pull
+        # request workflows from outside collaborators" select "require approval from
+        # all outside collaborators" to stop PR's from deploying to dev automatically.
+        # PRs will still be deployed automatically by code owners
+        run: |
+            techdocs-cli publish --publisher-type awsS3 \
+            --storage-name $TECHDOCS_S3_BUCKET_NAME \
+            --entity $ENTITY_NAMESPACE/$ENTITY_KIND/$ENTITY_NAME \
+            --awsEndpoint $AWS_ENDPOINT \
+            --awsS3ForcePathStyle true \
+            --awsBucketRootPath $TECHDOCS_S3_DEV_ROOT_PATH
+
+      - name: Publish docs to prod bucket
+        # Only publish to prod bucket on a push to main
+        # This could be changed to some other mechanism (ex: when a release is published)
+        if: ${{ github.ref == 'refs/heads/main' }}
+        run: |
+            techdocs-cli publish --publisher-type awsS3 \
+            --storage-name $TECHDOCS_S3_BUCKET_NAME \
+            --entity $ENTITY_NAMESPACE/$ENTITY_KIND/$ENTITY_NAME \
+            --awsEndpoint $AWS_ENDPOINT \
+            --awsS3ForcePathStyle true \

mkdocs.yml

@@ -1,5 +1,23 @@
 site_name: BC Gov Common Hosted Single Sign-on
 docs_dir: wiki
+edit_uri: edit/main/wiki/
 
+nav:
+  - Home: Home.md
+  - SSO Onboarding: SSO-Onboarding.md
+  - Using Your SSO Client: Using-Your-SSO-Client.md
+  - What is Keycloak @ BC Government: What-is-Keycloak-@-BC-Government?.md
+  - Our Partners and Useful Info: Our-Partners-and-Useful-Information.md
+  - Identity Provider Attribute Mapping: Identity-Provider-Attribute-Mapping.md
+  - Handling Authorization/Create a Role: Creating-a-Role.md
+  - Useful References: Useful-References.md
+  - Pathfinder SSO Uptime: Pathfinder-Uptime-Monitoring.md
+  - Our Service Level: Alerts-and-Us.md#/service-levels
 plugins:
-- techdocs-core
+  - techdocs-core
+  - ezlinks
+markdown_extensions:
+  - markdown_inline_mermaid
+  - md_in_html
+  - mkpatcher:
+      location: patcher.py

patcher.py

@@ -0,0 +1,40 @@
+import logging
+import re
+
+
+def patch(lines):
+	new_lines = []
+	for index, line in enumerate(lines):
+		# if we don't do any twiddling, carry the line through as-is
+		new_line = line
+
+		# match lines starting with a dash or bullet, with leading white space or not
+		bullet = re.match(r"^[\s]*[-\*]{1}\s", new_line)
+
+		if bullet:
+			logging.warning(f"Found line starting with bullet: '{new_line}'")
+
+			# match lines with leading white space
+			has_leading_white_space = re.match(r"^[\s]+[-\*]{1}\s", new_line)
+			prior_line_is_bullet = re.match(r"^[-\*]{1}", lines[index - 1].lstrip())
+			prior_line_is_blank = re.match(r"^\n", lines[index - 1].lstrip())
+
+			if not prior_line_is_bullet and not prior_line_is_blank:
+				logging.warning(f"Adding a new line before '{new_line}'")
+				new_lines.append("\n")
+
+			# first item in a bullet list - need to make sure it has no leading whitespace. leave as-is if it's not 1st
+			if has_leading_white_space and not prior_line_is_bullet:
+				logging.warning(f"Fixing line with bad whitespace: '{new_line}'")
+				new_line = new_line.lstrip()
+
+		# match lines starting with a dash or bullet, with leading white space or not
+		details_element = re.match(r"<(details+)(?![^>]*\/>)[^>]*>", new_line)
+
+		if details_element:
+			logging.warning(f"found line with details element: '{new_line}'")
+			new_line = new_line.replace("details", "details markdown=\"1\" ")
+			logging.warning(f"repaired line with details element: '{new_line}'")
+
+		new_lines.append(new_line)
+	return new_lines