Merge pull request #257 from jakkulabs/feature-automate-documentation

Automate creation and publishing of function documentation

.github/workflows/ps-module.yml

@@ -8,6 +8,7 @@ on:
       - tools/**
       - tests/**
       - .github/workflows/**
+      - mkdocs.yml
     tags:
       - v*
   pull_request:
@@ -54,12 +55,18 @@ jobs:
           name: Tools
           path: ${{ github.workspace }}/tools
 
+      - name: Upload Docs artifact
+        uses: actions/upload-artifact@v2
+        with:
+          name: docs
+          path: ${{ github.workspace }}/docs
+
   publish_test_results:
 
     name: "Publish Unit Tests Results"
+    if: always()
     needs: build
     runs-on: ubuntu-latest
-    if: always()
 
     steps:
       - name: Download Artifacts
@@ -72,6 +79,31 @@ jobs:
           github_token: ${{ secrets.GITHUB_TOKEN }}
           files: "./Tools/testResults.xml"
 
+  publish_docs:
+
+    name: "Publish Docs to GitHub Pages"
+    if: ${{ github.ref == 'refs/heads/master' }}
+    needs: build
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+
+      - name: Download Artifacts
+        uses: actions/download-artifact@v2
+
+      - name: Setup Python
+        uses: actions/setup-python@v2
+        with:
+          python-version: 3.x
+
+      - name: Install mkdocs-material
+        run: pip install mkdocs-material
+
+      - name: Run mkdocs
+        run: mkdocs gh-deploy --force
+
   test_release:
 
     name: Test Release module

README.md

@@ -130,3 +130,7 @@ Once complete you can run the UpdateDocumentation task to create new markdown fi
 ```
 
 The changes can then be committed back to the repository. Once pushed, they will be reflected in ReadTheDocs.
+
+**Documentation**
+
+Documentation for all functions in the module can be found [here](https://jakkulabs.github.io/PowervRA/).

mkdocs.yml

@@ -0,0 +1,5 @@
+site_name: PowervRA Module Documentation
+site_url: https://jakkulabs.github.io/PowervRA/
+
+theme:
+  name: material

tools/build.ps1

@@ -51,6 +51,10 @@ $Requirements = @(
     @{
         Name = "Pester"
         Version = "5.1.1"
+    },
+    @{
+        Name = "platyPS"
+        Version = "0.14.1"
     }
 )
 

tools/build.psake.ps1

@@ -8,7 +8,7 @@ properties {
 # --- Define the build tasks
 Task Default -depends Build
 Task Build -depends Lint, UpdateModuleManifest, CreateArtifact, CreateArchive
-Task BuildWithTests -depends Init, Build, ExecuteTest
+Task BuildWithTests -depends Init, Build, ExecuteTest, UpdateDocumentation
 
 Task Init {
 
@@ -155,24 +155,25 @@ Task ExecuteTest {
     Invoke-Pester -Configuration $config
 }
 
-# Task UpdateDocumentation {
+Task UpdateDocumentation {
 
-#     Write-Output "Updating Markdown help"
-#     $FunctionsPath = "$DocsDirectory\functions"
+    Write-Output "Updating Markdown help"
+    $FunctionsPath = "$DocsDirectory\functions"
 
-#     Remove-Item -Path $FunctionsPath -Recurse -Force -ErrorAction SilentlyContinue
-#     New-Item $FunctionsPath -ItemType Directory | Out-Null
+    Remove-Item -Path $FunctionsPath -Recurse -Force -ErrorAction SilentlyContinue
+    New-Item $FunctionsPath -ItemType Directory | Out-Null
 
-#     $PlatyPSParameters = @{
-#         Module = $ModuleName
-#         OutputFolder = $FunctionsPath
-#         NoMetadata = $true
-#     }
+    Import-Module -Name "$($ReleaseDirectoryPath)" -Global
 
-#     New-MarkdownHelp @PlatyPSParameters -ErrorAction SilentlyContinue -Verbose:$VerbosePreference | Out-Null
+    $PlatyPSParameters = @{
+        Module = $ModuleName
+        OutputFolder = $FunctionsPath
+        NoMetadata = $true
+    }
 
-#     # --- Ensure that index.md is present and up to date
-#     Write-Output "Updating index.md"
-#     Copy-Item -Path "$ENV:BHProjectPath\README.md" -Destination "$($DocsDirectory)\index.md" -Force -Verbose:$VerbosePreference | Out-Null
+    New-MarkdownHelp @PlatyPSParameters -ErrorAction SilentlyContinue -Verbose:$VerbosePreference | Out-Null
 
-# }
+    # --- Ensure that index.md is present and up to date
+    Write-Output "Updating index.md"
+    Copy-Item -Path "$ENV:BHProjectPath\README.md" -Destination "$($DocsDirectory)\index.md" -Force -Verbose:$VerbosePreference | Out-Null
+}