🚀 [Feature]: Publish module docs using Material on MkDocs (#34)

MariusStorhaug · web-flow · commit 0a5e46f0da41 · 2024-07-18T19:58:38.000Z
## Description - Uses newest version of Build-PSModule to build the docs folder for creating the site. - Publish docs to GitHub Pages using MkDocs. ## Type of change  - [ ] 📖 [Docs] - [ ] 🪲 [Fix] - [ ] 🩹 [Patch] - [ ] ⚠️ [Security fix] - [x] 🚀 [Feature] - [ ] 🌟 [Breaking change] ## Checklist  - [x] I have performed a self-review of my own code - [x] I have commented my code, particularly in hard-to-understand areas
diff --git a/.github/workflows/Workflow-Test-Default.yml b/.github/workflows/Workflow-Test-Default.yml
@@ -12,6 +12,8 @@ permissions:
   contents: write
   pull-requests: write
   statuses: write
+  pages: write
+  id-token: write
 
 jobs:
   WorkflowTestDefault:
diff --git a/.github/workflows/Workflow-Test-WithManifest.yml b/.github/workflows/Workflow-Test-WithManifest.yml
@@ -12,6 +12,8 @@ permissions:
   contents: write
   pull-requests: write
   statuses: write
+  pages: write
+  id-token: write
 
 jobs:
   WorkflowTestWithManifest:
diff --git a/.github/workflows/workflow.yml b/.github/workflows/workflow.yml
@@ -26,6 +26,11 @@ on:
         description: The path to the output directory for the documentation.
         required: false
         default: outputs/docs
+      SiteOutputPath:
+        type: string
+        description: The path to the output directory for the site.
+        required: false
+        default: outputs/site
       SkipTests:
         type: string
         description: Defines what types of tests to skip. Allowed values are 'All', 'SourceCode', 'Module', 'None', 'macOS', 'Windows', 'Linux', 'Desktop', 'Core'.
@@ -45,14 +50,19 @@ on:
         description: Whether the version is a prerelease.
         required: false
         default: false
+      PublishDocs:
+        type: boolean
+        description: Whether to publish the documentation using MkDocs and GitHub Pages.
+        required: false
+        default: true
 
 env:
   GITHUB_TOKEN: ${{ github.token }} # Used for GitHub CLI authentication
 
 permissions:
-  contents: write
-  pull-requests: write
-  statuses: write
+  contents: write      # to checkout the repo and create releases on the repo
+  pull-requests: write # to write comments to PRs
+  statuses: write      # to update the status of the workflow from linter
 
 jobs:
   TestSourceCode-pwsh-ubuntu-latest:
@@ -533,10 +543,9 @@ jobs:
 
   PublishModule:
     name: Publish module
-    if: ${{ needs.TestModuleStatus.result == 'success' && needs.LintDocs.result == 'success' && !cancelled() && github.event_name == 'pull_request' }}
+    if: ${{ needs.TestModuleStatus.result == 'success' && !cancelled() && github.event_name == 'pull_request' }}
     needs:
       - TestModuleStatus
-      - LintDocs
     runs-on: ubuntu-latest
     steps:
       - name: Checkout Code
@@ -554,17 +563,147 @@ jobs:
           name: module
           path: ${{ inputs.ModulesOutputPath }}
 
-      - name: Download docs artifact
-        uses: actions/download-artifact@v4
-        with:
-          name: docs
-          path: ${{ inputs.DocsOutputPath }}
-
       - name: Publish module
         uses: PSModule/Publish-PSModule@v1
         with:
           Name: ${{ inputs.Name }}
           ModulePath: ${{ inputs.ModulesOutputPath }}
-          DocsPath: ${{ inputs.DocsOutputPath }}
           APIKey: ${{ secrets.APIKEY }}
           WhatIf: ${{ inputs.TestProcess }}
+
+  BuildSite:
+    name: Build Site
+    if: ${{ inputs.PublishDocs && needs.LintDocs.result == 'success' && !cancelled() }}
+    needs: LintDocs
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          ref: ${{ github.event.pull_request.head.sha }}
+
+      - name: Initialize environment
+        uses: PSModule/Initialize-PSModule@v1
+        with:
+          Version: ${{ inputs.Version }}
+          Prerelease: ${{ inputs.Prerelease }}
+
+      - name: Download docs artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: docs
+          path: ${{ inputs.DocsOutputPath }}
+
+      - name: Debug File system
+        shell: pwsh
+        run: |
+          Get-ChildItem -Path $env:GITHUB_WORKSPACE -Recurse | Select-Object -ExpandProperty FullName | Sort-Object
+
+      - name: Debug Env vars
+        shell: pwsh
+        run: |
+          Get-ChildItem env: | Format-Table
+
+      - uses: actions/configure-pages@v5
+
+      - name: Install mkdoks-material
+        shell: pwsh
+        run: |
+          pip install mkdocs-material
+          pip install mkdocs-git-authors-plugin
+          pip install mkdocs-git-revision-date-localized-plugin
+          pip install mkdocs-git-committers-plugin-2
+
+      - name: Run Script
+        shell: pwsh
+        run: |
+          $ModuleName = '${{ inputs.Name }}'
+
+          if (-not $ModuleName) {
+              $ModuleName = $env:GITHUB_REPOSITORY -replace '.+/'
+          }
+          Write-Verbose "Module name: $ModuleName"
+
+          $ModuleSourcePath = Join-Path (Get-Location) -ChildPath '${{ inputs.Path }}'
+          $DocsOutputPath = Join-Path (Get-Location) -ChildPath "${{ inputs.DocsOutputPath }}/$ModuleName"
+          $SiteOutputPath = Join-Path (Get-Location) -ChildPath '${{ inputs.SiteOutputPath }}'
+
+          $functionDocsFolderPath = Join-Path -Path $SiteOutputPath -ChildPath 'docs/Functions'
+          $functionDocsFolder = New-Item -Path $functionDocsFolderPath -ItemType Directory -Force
+          Get-ChildItem -Path $DocsOutputPath -Recurse -Force -Include '*.md' | Copy-Item -Destination $functionDocsFolder -Recurse -Force
+          Get-ChildItem -Path $functionDocsFolder -Recurse -Force -Include '*.md' | ForEach-Object {
+              $fileName = $_.Name
+              $hash = (Get-FileHash -Path $_.FullName -Algorithm SHA256).Hash
+              Start-LogGroup " - [$fileName] - [$hash]"
+              Show-FileContent -Path $_
+              Stop-LogGroup
+          }
+
+          Start-LogGroup 'Build docs - Process about topics'
+          $aboutDocsFolderPath = Join-Path -Path $SiteOutputPath -ChildPath 'docs/About'
+          $aboutDocsFolder = New-Item -Path $aboutDocsFolderPath -ItemType Directory -Force
+          $aboutSourceFolder = Get-ChildItem -Path $ModuleSourcePath -Directory | Where-Object { $_.Name -eq 'en-US' }
+          Get-ChildItem -Path $aboutSourceFolder -Filter *.txt | Copy-Item -Destination $aboutDocsFolder -Force -Verbose -PassThru |
+              Rename-Item -NewName { $_.Name -replace '.txt', '.md' }
+          Stop-LogGroup
+
+          Start-LogGroup 'Build docs - Copy icon to assets'
+          $assetsFolderPath = Join-Path -Path $SiteOutputPath -ChildPath 'docs/Assets'
+          $null = New-Item -Path $assetsFolderPath -ItemType Directory -Force
+          $rootPath = Split-Path -Path $ModuleSourcePath -Parent
+          $iconPath = Join-Path -Path $rootPath -ChildPath 'icon\icon.png'
+          Copy-Item -Path $iconPath -Destination $assetsFolderPath -Force -Verbose
+
+          Start-LogGroup 'Build docs - Copy readme.md'
+          $rootPath = Split-Path -Path $ModuleSourcePath -Parent
+          $readmePath = Join-Path -Path $rootPath -ChildPath 'README.md'
+          $readmeTargetPath = Join-Path -Path $SiteOutputPath -ChildPath 'docs/README.md'
+          Copy-Item -Path $readmePath -Destination $readmeTargetPath -Force -Verbose
+          Stop-LogGroup
+
+          Start-LogGroup 'Build docs - Create mkdocs.yml'
+          $rootPath = Split-Path -Path $ModuleSourcePath -Parent
+          # This should be moved to an action so that we can use a default one, and not have to copy it from the repo.
+          $mkdocsSourcePath = Join-Path -Path $rootPath -ChildPath 'mkdocs.yml'
+          $mkdocsTargetPath = Join-Path -Path $SiteOutputPath -ChildPath 'mkdocs.yml'
+          $mkdocsContent = Get-Content -Path $mkdocsSourcePath -Raw
+          $mkdocsContent = $mkdocsContent.Replace('-{{ REPO_NAME }}-', $ModuleName)
+          $mkdocsContent = $mkdocsContent.Replace('-{{ REPO_OWNER }}-', $env:GITHUB_REPOSITORY_OWNER)
+          $mkdocsContent | Set-Content -Path $mkdocsTargetPath -Force
+          Show-FileContent -Path $mkdocsTargetPath
+          Stop-LogGroup
+
+      - name: Debug File system
+        shell: pwsh
+        run: |
+          Get-ChildItem -Path $env:GITHUB_WORKSPACE -Recurse | Select-Object -ExpandProperty FullName | Sort-Object
+
+      - name: Build mkdocs-material project
+        working-directory: ${{ inputs.SiteOutputPath }}
+        shell: pwsh
+        run: |
+          Start-LogGroup 'Build docs - mkdocs build - content'
+          Show-FileContent -Path mkdocs.yml
+          Stop-LogGroup
+          Start-LogGroup 'Build docs - mkdocs build'
+          mkdocs build --config-file mkdocs.yml --site-dir ${{ github.workspace }}/_site
+          Stop-LogGroup
+
+      - uses: actions/upload-pages-artifact@v3
+
+  PublishSite:
+    name: Publish documentation
+    if: ${{ inputs.PublishDocs && needs.BuildSite.result == 'success' && !cancelled() && github.event_name == 'pull_request' && github.event.pull_request.merged == true }}
+    needs: BuildSite
+    permissions:
+      pages: write    # to deploy to Pages
+      id-token: write # to verify the deployment originates from an appropriate source
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
diff --git a/README.md b/README.md
@@ -73,6 +73,8 @@ jobs:
 | `Path` | `string` | The path to the source code of the module. | `false` | `src` |
 | `ModulesOutputPath` | `string` | The path to the output directory for the modules. | `false` | `outputs/modules` |
 | `DocsOutputPath` | `string` | The path to the output directory for the documentation. | `false` | `outputs/docs` |
+| `PublishDocs` | `boolean` | Whether to publish the documentation using MkDocs and GitHub Pages. | `false` | `true` |
+| `SiteOutputPath` | `string` | The path to the output directory for the site. | `false` | `outputs/site` |
 | `SkipTests` | `string` | Defines what types of tests to skip. Allowed values are 'All', 'SourceCode', 'Module', 'None', 'macOS', 'Windows', 'Linux', 'Desktop', 'Core'. | false | `None` |
 | `TestProcess` | `boolean` | Whether to test the process. | false | `false` |
 
@@ -93,11 +95,23 @@ If running the action in a restrictive mode, the following permissions needs to
 
 ```yaml
 permissions:
-  contents: write # Required to create releases
-  pull-requests: write # Required to create comments on the PRs
-  statuses: write # Required to update the status of the PRs from the linter
+  contents: write      # Create releases
+  pull-requests: write # Create comments on the PRs
+  statuses: write      # Update the status of the PRs from the linter
 ```
 
+### Publishing to GitHub Pages
+
+To publish the documentation to GitHub Pages, the action requires the following permissions:
+
+```yaml
+permissions:
+  pages: write    # Deploy to Pages
+  id-token: write # Verify the deployment originates from an appropriate source
+```
+
+For more info see [Deploy GitHub Pages site](https://github.com/marketplace/actions/deploy-github-pages-site).
+
 ## Compatibility
 
 The action is compatible with the following configurations:
diff --git a/tests/README.md b/tests/README.md
@@ -0,0 +1,3 @@
+# Test module
+
+This is a test readme.
diff --git a/tests/icon/icon.png b/tests/icon/icon.png
diff --git a/tests/mkdocs.yml b/tests/mkdocs.yml
@@ -0,0 +1,75 @@
+site_name: -{{ REPO_NAME }}-
+theme:
+  name: material
+  language: en
+  font:
+    text: Roboto
+    code: Sono
+  logo: Assets/icon.png
+  favicon: Assets/icon.png
+  palette:
+    # Palette toggle for automatic mode
+    - media: "(prefers-color-scheme)"
+      toggle:
+        icon: material/link
+        name: Switch to dark mode
+    # Palette toggle for dark mode
+    - media: '(prefers-color-scheme: dark)'
+      scheme: slate
+      toggle:
+        primary: black
+        accent: green
+        icon: material/toggle-switch-off-outline
+        name: Switch to light mode
+    # Palette toggle for light mode
+    - media: '(prefers-color-scheme: light)'
+      scheme: default
+      toggle:
+        primary: indigo
+        accent: green
+        icon: material/toggle-switch
+        name: Switch to system preference
+  icon:
+    repo: material/github
+  features:
+    - navigation.instant
+    - navigation.instant.progress
+    - navigation.indexes
+    - navigation.top
+    - navigation.tracking
+    - navigation.expand
+    - search.suggest
+    - search.highlight
+
+repo_name: -{{ REPO_OWNER }}-/-{{ REPO_NAME }}-
+repo_url: https://github.com/-{{ REPO_OWNER }}-/-{{ REPO_NAME }}-
+
+plugins:
+  - search
+
+markdown_extensions:
+  - toc:
+      permalink: true # Adds a link icon to headings
+  - attr_list
+  - admonition
+  - md_in_html
+  - pymdownx.details # Enables collapsible admonitions
+
+extra:
+  social:
+    - icon: fontawesome/brands/discord
+      link: https://discord.gg/jedJWCPAhD
+      name: -{{ REPO_OWNER }}- on Discord
+    - icon: fontawesome/brands/github
+      link: https://github.com/-{{ REPO_OWNER }}-/
+      name: -{{ REPO_OWNER }}- on GitHub
+  consent:
+    title: Cookie consent
+    description: >-
+      We use cookies to recognize your repeated visits and preferences, as well
+      as to measure the effectiveness of our documentation and whether users
+      find what they're searching for. With your consent, you're helping us to
+      make our documentation better.
+    actions:
+      - accept
+      - reject

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+# Test module`
	`2`	`+`
	`3`	`+This is a test readme.`