(#18) Build docs automatically

With this commit the build pipeline will handle processing of the
PowerShell scripts, writing Markdown help from them. It will then
call on mkdocs in the pipeline to create a new version of the docs.

Author: steviecoaster

.github/workflows/build.yml

@@ -62,6 +62,19 @@ jobs:
           draft: false
           prerelease: ${{ github.ref != 'refs/heads/main' }}
 
+      - name: Write MD Docs with PlatyPS
+        run: .\build.ps1 -WriteMdDocs -SemVer "${{ steps.gitversion.outputs.LegacySemVerPadded }}"
+        shell: pwsh
+
+      - name: Deploy docs
+        uses: mhausenblas/mkdocs-deploy-gh-pages@nomaterial
+        # Or use mhausenblas/mkdocs-deploy-gh-pages@nomaterial to build without the mkdocs-material theme
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          CONFIG_FILE: .\mkdocs_template\mkdocs.yml
+          EXTRA_PACKAGES: build-base
+          # GITHUB_DOMAIN: github.myenterprise.com
+
       - name: Publish Module
         if: ${{ github.ref == 'refs/heads/main' }}
         run: .\build.ps1 -DeployToGallery -SemVer "${{ steps.gitversion.outputs.LegacySemVerPadded }}"

build.ps1

@@ -16,6 +16,18 @@ param(
     [Switch]
     $DeployToGallery,
 
+    [Parameter()]
+    [Switch]
+    $WriteMdDocs,
+
+    [Parameter()]
+    [Switch]
+    $MkDocsPublish,
+
+    [Parameter()]
+    [Switch]
+    $GHPages,
+
     [Parameter()]
     [Switch]
     $Choco,
@@ -92,5 +104,40 @@ process {
                 choco push $_.FullName -s https://push.chocolatey.org --api-key="'$($env:ChocoApiKey)'"
             }
         }
+
+        $WriteMdDocs {
+            if (Test-Path $root\Output\BeautifulDocs) {
+                if ($env:PSModulePath.Split(';') -notcontains "$root\Output") {
+                    $env:PSModulePath = "$root\Output;$env:PSModulePath"
+                }
+                Import-Module BeautifulDocs -Force
+                Import-Module PlatyPS -Force
+
+                New-MarkdownHelp -Module BeautifulDocs -OutputFolder $root\docs
+
+            }
+        }
+
+        $MkDocsPublish {
+            $mkDocsRoot = Join-Path $root 'mkdocs_template'
+            Push-Location $mkDocsRoot
+            $mkDocsArgs = @('build')
+
+            & 'C:\Python39\Scripts\mkdocs.exe' @mkDocsArgs
+        }
+
+        $GHPages {
+            # Write your PowerShell commands here.
+            git config --global user.name 'Stephen Valdinger'
+            git config --global user.email '[email protected]'
+            git remote rm origin
+            $url = 'https://steviecoaster:' + $env:GH_TOKEN + '@github.com/steviecoaster/BeautifulDocs.git'
+            git remote add origin $url
+
+            $mkDocsArgs = @('gh-deploy','--force')
+
+            Set-Location .\mkdocs_template
+            & 'C:\Python39\Scripts\mkdocs.exe' @mkDocsArgs
+        }
     }
 }