deploy auto generated docs to GitHub pages

.github/workflows/ci-publish-docs-branch.yml

@@ -6,11 +6,28 @@ on: # yamllint disable-line rule:truthy
     paths:
       - "./BenchPress/Helpers/BenchPress.Azure/*.psm1"
 
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+env:
+  BUILD_PATH: "./docs-site"
+
 jobs:
   publish-docs-branch:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
+      - name: Checkout
+        uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+          ref: docs
+          token: ${{ secrets.DOCS_ACTION_TOKEN }}
 
       - name: Install Platyps
         shell: pwsh
@@ -20,15 +37,52 @@ jobs:
 
       - name: Create and checkout new docs branch
         run: |
-          git config --global user.name "github-actions[bot]"
-          git config --global user.email "github-actions[bot]@users.noreply.github.com"
+          git config --global user.name "github-actions"
+          git config --global user.email "github-actions@github.com"
           git checkout -b docs
 
       - name: Generate docs
         shell: pwsh
         run: |
           Import-Module ./BenchPress/Helpers/BenchPress.Azure/BenchPress.Azure.psd1
-          New-MarkdownHelp -Module BenchPress.Azure -OutputFolder ./docs
+
+          New-Item -ItemType Directory -Path "./docs/helpers" -Force
+
+          New-MarkdownHelp -Module BenchPress.Azure -OutputFolder ./docs/helpers -Force -AlphabeticParamsOrder -UseFullTypeName -NoMetadata
+
+          foreach ($File in Get-ChildItem ./docs/helpers/*.md) {
+            Write-Host "Updating $File"
+            # Add front matter
+            $Frontmatter = ""
+            $FrontMatter += "---`r`n"
+            $FrontMatter += "WARNING: `"PLEASE DO NOT MODIFY THIS FILE, IT'LL BE OVERWRITTEN`"`r`n"
+            $FrontMatter += "layout: `"../../layouts/main.astro`"`r`n"
+            $FrontMatter += "title: `"$($File.BaseName)`"`r`n"
+            $FrontMatter += "module: `"BenchPress.Azure`"`r`n"
+            $FrontMatter += "version: `"${{ github.sha }}`"`r`n"
+            $FrontMatter += "updatedOn: `"$(Get-Date -Format "yyyy-MM-dd HH:mm K")`"`r`n"
+            $FrontMatter += "---`r`n"
+            # Fix escaping issues
+            $Content = Get-Content $File -Raw
+            $Content = $Content -Replace '\\`', '`'
+            $Content = $Content -Replace "\\\[", "["
+            $Content = $Content -Replace "\\\]", "]"
+            # Fix syntax highlighting
+            $Lines = $Content -Split "`r`n"
+            for ($i = 0; $i -lt $Lines.Length; $i++) {
+              if ($Lines[$i] -match "^## SYNTAX") {
+                $j = $i + 2
+                if ($Lines[$j] -match '```') {
+                  $Lines[$j] = $Lines[$j] -Replace '```', '```powershell'
+                }
+              }
+            }
+            # Write out the file back
+            Set-Content $File ($FrontMatter + ($Lines -join "`r`n"))
+          }
+          Pop-Location
+          New-Item -ItemType Directory -Path "./docs-site/src/pages/docs" -Force
+          Copy-Item -Path "./docs/helpers/*" -Destination "./docs-site/src/pages/docs" -Include "*.md" -Recurse -Force
 
       - name: If there are changes push the branch
         run: |
@@ -38,3 +92,48 @@ jobs:
             git commit -m "docs: updating generated documentation"
             git push origin docs
           fi
+
+      - name: Detect package manager
+        id: detect-package-manager
+        run: |
+          echo "manager=npm" >> $GITHUB_OUTPUT
+          echo "command=ci" >> $GITHUB_OUTPUT
+          echo "runner=npx --no-install" >> $GITHUB_OUTPUT
+      - name: Setup Node
+        uses: actions/setup-node@v3
+        with:
+          node-version: "16"
+          cache: ${{ steps.detect-package-manager.outputs.manager }}
+          cache-dependency-path: ${{ env.BUILD_PATH }}/package-lock.json
+
+      - name: Setup Pages
+        id: pages
+        uses: actions/configure-pages@v2
+
+      - name: Install dependencies
+        run: ${{ steps.detect-package-manager.outputs.manager }} ${{ steps.detect-package-manager.outputs.command }}
+        working-directory: ${{ env.BUILD_PATH }}
+
+      - name: Build with Astro
+        run: |
+          ${{ steps.detect-package-manager.outputs.runner }} astro build \
+            --site "${{ steps.pages.outputs.origin }}" \
+            --base "${{ steps.pages.outputs.base_path }}"
+        working-directory: ${{ env.BUILD_PATH }}
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v1
+        with:
+          path: ${{ env.BUILD_PATH }}/dist
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    needs: build
+    runs-on: ubuntu-latest
+    name: Deploy
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v1

.gitignore

@@ -110,3 +110,5 @@ StyleCopReport.xml
 !?*.[Cc]ache/
 
 megalinter-reports/
+
+node_modules

docs-site/astro.config.mjs

@@ -0,0 +1,15 @@
+import { defineConfig } from "astro/config";
+
+import tailwind from "@astrojs/tailwind";
+
+export default defineConfig({
+  base: "/benchpress",
+  markdown: {
+    shikiConfig: {
+      theme: "dark-plus"
+    }
+  },
+  integrations: [tailwind({
+    config: { applyBaseStyles: false },
+  })]
+});

docs-site/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "benchpress.docs-site",
+  "type": "module",
+  "version": "0.0.1",
+  "private": true,
+  "scripts": {
+    "dev": "astro dev",
+    "start": "astro dev",
+    "build": "astro build",
+    "preview": "astro preview",
+    "astro": "astro"
+  },
+  "dependencies": {
+    "@astrojs/tailwind": "2.1.3",
+    "astro": "1.9.2",
+    "tailwindcss": "3.2.4"
+  }
+}

docs-site/src/env.d.ts

@@ -0,0 +1 @@
+/// <reference types="astro/client" />

docs-site/src/layouts/main.astro

@@ -0,0 +1,66 @@
+---
+import "../styles/global.css";
+
+const posts = await Astro.glob('../pages/docs/*.md');
+---
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+  </head>
+  <body>
+    <div class="flex-row min-h-screen dark:bg-zinc-800 dark:text-zinc-50">
+      <nav class="flex items-center p-3 border-b shadow-sm">
+        <a class="text-4xl hover:text-green-600" href=`${import.meta.env.BASE_URL}`>💪 BenchPress</a>
+        <span class="flex-grow"></span>
+        <a class="hover:text-green-600" target="_blank" href="https://github.com/azure/benchpress">GitHub ↗️</a>
+        <button class="p-2" id="btnTheme"></button>
+      </nav>
+      <main class="flex">
+        <aside class="w-96 p-3">
+          <h2 class="font-semibold border-b pb-2 mb-2">Helpers</h2>
+          <ul>
+          {posts.map((post) => (
+            <li><a class="hover:text-green-600" href={post.url}>{post.frontmatter.title}</a></li>
+          ))}
+          </ul>
+        </aside>
+        <article class="p-3 flex flex-grow justify-center">
+          <div class="max-w-4xl mt-4">
+            <slot />
+          </div>
+        </article>
+      </main>
+    </div>
+    <script is:inline>
+      const theme = (() => {
+        if (typeof localStorage !== "undefined" && localStorage.getItem("theme")) {
+          return localStorage.getItem("theme");
+        }
+        if (window.matchMedia("(prefers-color-scheme: dark)").matches) {
+          return "dark";
+        }
+        return "light";
+      })();
+      if (theme === "light") {
+        document.documentElement.classList.remove("dark");
+        document.getElementById("btnTheme").innerHTML = "🌙";
+      } else {
+        document.documentElement.classList.add("dark");
+        document.getElementById("btnTheme").innerHTML = "☀️";
+      }
+      window.localStorage.setItem("theme", theme);
+      document.getElementById("btnTheme").addEventListener("click", () => {
+        if (document.documentElement.classList.contains("dark")) {
+          document.documentElement.classList.remove("dark");
+          document.getElementById("btnTheme").innerHTML = "🌙";
+          window.localStorage.setItem("theme", "light");
+        } else {
+          document.documentElement.classList.add("dark");
+          document.getElementById("btnTheme").innerHTML = "☀️";
+          window.localStorage.setItem("theme", "dark");
+        }
+      });
+    </script>
+  </body>
+</html>

docs-site/src/pages/index.md

@@ -0,0 +1,18 @@
+---
+layout: "../layouts/main.astro"
+---
+# Benchpress testing framework
+
+This framework is intended to work as a testing framework for Azure deployment features by using Bicep.
+
+In order to see how you can work with this framework you can find one sample bicep file in the folder samples that will be deployed by using one PowerShell script.
+
+## Getting Started
+
+You can find the PowerShell script in the folder scripts. This script will deploy the bicep file in the samples folder.
+
+## Prerequisites
+
+* [Powershell](https://docs.microsoft.com/en-us/powershell/scripting/install/installing-powershell?view=powershell-7.1)
+* [Azure Subscription](https://azure.microsoft.com/en-us/free/)
+* [Powershell SDK for Azure](https://docs.microsoft.com/en-us/powershell/azure/install-az-ps?view=azps-6.4.0)

docs-site/src/styles/global.css

@@ -0,0 +1,40 @@
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+@layer components {
+  h1 {
+    @apply text-4xl;
+  }
+  h2 {
+    @apply text-2xl;
+  }
+  h3 {
+    @apply text-xl;
+  }
+  article div ul {
+    @apply list-disc list-inside;
+  }
+  article div a {
+    @apply text-green-600 hover:underline;
+  }
+
+  article h1 {
+    @apply my-6 pb-4 border-b;
+  }
+  article h2 {
+    @apply my-4 pb-4 border-b;
+  }
+  article h3 {
+    @apply my-2;
+  }
+  article p {
+    @apply my-1;
+  }
+  article pre {
+    @apply my-2 p-4 rounded;
+  }
+  article p code {
+    @apply dark:bg-zinc-900 bg-zinc-300 p-1 rounded;
+  }
+}

docs-site/tailwind.config.cjs

@@ -0,0 +1,10 @@
+/** @type {import('tailwindcss').Config} */
+
+module.exports = {
+  content: ['./src/**/*.{astro,html,js,jsx,md,mdx,svelte,ts,tsx,vue}'],
+  darkMode: "class",
+  theme: {
+    extend: {},
+  },
+  plugins: [],
+}

docs-site/tsconfig.json

@@ -0,0 +1,3 @@
+{
+  "extends": "astro/tsconfigs/strict"
+}