techthoughts2 · techthoughts2 · Sep 12, 2020 · Sep 6, 2020 · Sep 7, 2020 · Sep 7, 2020
diff --git a/.github/CHANGELOG.md b/.github/CHANGELOG.md
@@ -5,6 +5,28 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.9.7]
+
+- Catesta template module changes
+  - Fixed missing !Sub Intrinsic function reference in PowerShellCodeBuildGit.yml
+  - Improved error message when modules fail to install with install_modules.ps1 and actions_bootstrap.ps1
+  - Improved output message when missing help information found during *.build.ps1
+  - Improved PSModule.build.ps1
+    - Resolved bug where CreateMarkdownHelp fails if module not imported
+    - Added additional checks for missing markdown documentation
+    - Added build steps which import the module manifest explicitly
+    - Corrected output in AnalyzeTests to not write out the word green
+    - Parent level markdown docs will now be updated on each build
+  - Adjusted ExportedFunctions.Tests.ps1 to check for included example rather than example count
+- Catesta primary module changes
+  - Improved PSModule.build.ps1
+    - Resolved bug where CreateMarkdownHelp fails if module not imported
+    - Added additional checks for missing markdown documentation
+    - Added build steps which import the module manifest explicitly
+    - Adjusted ExportedFunctions.Tests.ps1 to check for included example rather than example count
+- Updated a few areas of documentation/help to provide more clarification
+- Updated .vscode settings to use ```${workspaceFolderBasename}``` instead of hard-coded Catesta name
+
 ## [0.9.0]
 
 - Catesta primary module changes

diff --git a/.vscode/tasks.json b/.vscode/tasks.json
@@ -60,7 +60,7 @@
             "label": ".",
             "type": "shell",
             "problemMatcher": "$msCompile",
-            "command": "$PSVersionTable;Invoke-Build -Task . -File '${workspaceFolder}/src/Catesta.build.ps1'",
+            "command": "$PSVersionTable;Invoke-Build -Task . -File '${workspaceFolder}/src/${workspaceFolderBasename}.build.ps1'",
             "group": {
                 "kind": "test",
                 "isDefault": true
@@ -70,67 +70,67 @@
             "label": "TestLocal",
             "type": "shell",
             "problemMatcher": "$msCompile",
-            "command": "Invoke-Build -Task TestLocal -File '${workspaceFolder}/src/Catesta.build.ps1'"
+            "command": "Invoke-Build -Task TestLocal -File '${workspaceFolder}/src/${workspaceFolderBasename}.build.ps1'"
         },
         {
             "label": "HelpLocal",
             "type": "shell",
             "problemMatcher": "$msCompile",
-            "command": "Invoke-Build -Task HelpLocal -File '${workspaceFolder}/src/Catesta.build.ps1'"
+            "command": "Invoke-Build -Task HelpLocal -File '${workspaceFolder}/src/${workspaceFolderBasename}.build.ps1'"
         },
         {
             "label": "Clean",
             "type": "shell",
             "problemMatcher": "$msCompile",
-            "command": "Invoke-Build -Task Clean -File '${workspaceFolder}/src/Catesta.build.ps1'"
+            "command": "Invoke-Build -Task Clean -File '${workspaceFolder}/src/${workspaceFolderBasename}.build.ps1'"
         },
         {
             "label": "ValidateRequirements",
             "type": "shell",
             "problemMatcher": "$msCompile",
-            "command": "Invoke-Build -Task ValidateRequirements -File '${workspaceFolder}/src/Catesta.build.ps1'"
+            "command": "Invoke-Build -Task ValidateRequirements -File '${workspaceFolder}/src/${workspaceFolderBasename}.build.ps1'"
         },
         {
             "label": "Analyze",
             "type": "shell",
             "problemMatcher": "$msCompile",
-            "command": "Invoke-Build -Task Analyze -File '${workspaceFolder}/src/Catesta.build.ps1'"
+            "command": "Invoke-Build -Task Analyze -File '${workspaceFolder}/src/${workspaceFolderBasename}.build.ps1'"
         },
         {
             "label": "AnalyzeTests",
             "type": "shell",
             "problemMatcher": "$msCompile",
-            "command": "Invoke-Build -Task AnalyzeTests -File '${workspaceFolder}/src/Catesta.build.ps1'"
+            "command": "Invoke-Build -Task AnalyzeTests -File '${workspaceFolder}/src/${workspaceFolderBasename}.build.ps1'"
         },
         {
             "label": "FormattingCheck",
             "type": "shell",
             "problemMatcher": "$msCompile",
-            "command": "Invoke-Build -Task FormattingCheck -File '${workspaceFolder}/src/Catesta.build.ps1'"
+            "command": "Invoke-Build -Task FormattingCheck -File '${workspaceFolder}/src/${workspaceFolderBasename}.build.ps1'"
         },
         {
             "label": "Test",
             "type": "shell",
             "problemMatcher": "$msCompile",
-            "command": "Invoke-Build -Task Test -File '${workspaceFolder}/src/Catesta.build.ps1'"
+            "command": "Invoke-Build -Task Test -File '${workspaceFolder}/src/${workspaceFolderBasename}.build.ps1'"
         },
         {
             "label": "DevCC",
             "type": "shell",
             "problemMatcher": "$msCompile",
-            "command": "Invoke-Build -Task DevCC -File '${workspaceFolder}/src/Catesta.build.ps1'"
+            "command": "Invoke-Build -Task DevCC -File '${workspaceFolder}/src/${workspaceFolderBasename}.build.ps1'"
         },
         {
             "label": "Build",
             "type": "shell",
             "problemMatcher": "$msCompile",
-            "command": "Invoke-Build -Task Build -File '${workspaceFolder}/src/Catesta.build.ps1'"
+            "command": "Invoke-Build -Task Build -File '${workspaceFolder}/src/${workspaceFolderBasename}.build.ps1'"
         },
         {
             "label": "InfraTest",
             "type": "shell",
             "problemMatcher": "$msCompile",
-            "command": "Invoke-Build -Task InfraTest -File '${workspaceFolder}/src/Catesta.build.ps1'"
+            "command": "Invoke-Build -Task InfraTest -File '${workspaceFolder}/src/${workspaceFolderBasename}.build.ps1'"
         }
     ]
-}
+}
diff --git a/README.md b/README.md
@@ -105,7 +105,16 @@ New-PowerShellProject -CICDChoice 'ModuleOnly' -DestinationPath c:\path\ModuleOn
 1. Write your module (the hardest part)
     * All build testing can be done locally by navigating to src and running ```Invoke-Build```
     * If using VSCode as your primary editor you can use tasks to perform various local actions
-      * ```Press Ctrl+P, then type 'task test'```
+      * Examples:
+        * ```Press Ctrl+P, then type 'task .'``` - Runs complete build (all tasks)
+        * ```Press Ctrl+P, then type 'task Test'``` - Invokes all Pester Unit Tests
+        * ```Press Ctrl+P, then type 'task Analyze'``` - Invokes Script Analyzer checks
+        * ```Press Ctrl+P, then type 'task DevCC'``` - Generates generate xml file to graphically display code coverage in VSCode using [Coverage Gutters](https://marketplace.visualstudio.com/items?itemName=ryanluker.vscode-coverage-gutters)
+1. Add any module dependencies to your CI/CD bootstrap file:
+    * AWS: install_modules.ps1
+    * GitHub Actions: actions_bootstrap.ps1
+    * Azure: actions_bootstrap.ps1
+    * AppVeyor: actions_bootstrap.ps1
 1. Commit your project to desired repository that is integrated with your CI/CD platform. This will trigger the build actions.
 1. Evaluate results of your builds and [display your README badges](https://github.com/techthoughts2/Catesta/blob/master/docs/Catesta-FAQ.md#how-do-i-display-the-badges-for-my-project) proudly!
 

diff --git a/actions_bootstrap.ps1 b/actions_bootstrap.ps1
@@ -53,6 +53,6 @@ foreach ($module in $modulesToInstall) {
     catch {
         $message = 'Failed to install {0}' -f $module.ModuleName
         "  - $message"
-        throw $message
+        throw
     }
-}
+}
diff --git a/docs/Catesta-AWS.md b/docs/Catesta-AWS.md
@@ -52,6 +52,13 @@ Scaffolds a new PowerShell module project intended for CI/CD workflow using [AWS
       * The generated CFN template will guide you through the process. This CFN is different than the GitHub one in that you only need to deploy it once. This CFN will be dynamically altered based on your buildspec choice specified during the plaster process. If you choose all three, the CFN will deploy all required resources to support all three build types.
 1. Write a kick-ass module (the hardest part)
     * All build testing can be done locally by navigating to src and running ```Invoke-Build```
+    * If using VSCode as your primary editor you can use tasks to perform various local actions
+      * Examples:
+        * ```Press Ctrl+P, then type 'task .'``` - Runs complete build (all tasks)
+        * ```Press Ctrl+P, then type 'task Test'``` - Invokes all Pester Unit Tests
+        * ```Press Ctrl+P, then type 'task Analyze'``` - Invokes Script Analyzer checks
+        * ```Press Ctrl+P, then type 'task DevCC'``` - Generates generate xml file to graphically display code coverage in VSCode using [Coverage Gutters](https://marketplace.visualstudio.com/items?itemName=ryanluker.vscode-coverage-gutters)
+1. *The comment based help in your functions will be used to generate/update markdown docs for your module in the docs folder.*
 1. Upload to your desired repository which now has a triggered/monitored build action.
 1. Evaluate results of your build and display your AWS CodeBuild badge proudly!
 

diff --git a/docs/Catesta-AppVeyor.md b/docs/Catesta-AppVeyor.md
@@ -41,6 +41,13 @@ Scaffolds a new PowerShell module project intended for CI/CD workflow using * [A
         * [M] MacOS
 1. Write a kick-ass module (the hardest part)
     * All build testing can be done locally by navigating to src and running ```Invoke-Build```
+    * If using VSCode as your primary editor you can use tasks to perform various local actions
+      * Examples:
+        * ```Press Ctrl+P, then type 'task .'``` - Runs complete build (all tasks)
+        * ```Press Ctrl+P, then type 'task Test'``` - Invokes all Pester Unit Tests
+        * ```Press Ctrl+P, then type 'task Analyze'``` - Invokes Script Analyzer checks
+        * ```Press Ctrl+P, then type 'task DevCC'``` - Generates generate xml file to graphically display code coverage in VSCode using [Coverage Gutters](https://marketplace.visualstudio.com/items?itemName=ryanluker.vscode-coverage-gutters)
+1. *The comment based help in your functions will be used to generate/update markdown docs for your module in the docs folder.*
 1. Upload to your desired repository which now has a triggered/monitored build action.
 1. Evaluate results of your build and display your AppVeyor badge proudly!
 

diff --git a/docs/Catesta-Azure.md b/docs/Catesta-Azure.md
@@ -41,6 +41,13 @@ Scaffolds a new PowerShell module project intended for CI/CD workflow using [Azu
         * [M] MacOS
 1. Write a kick-ass module (the hardest part)
     * All build testing can be done locally by navigating to src and running ```Invoke-Build```
+    * If using VSCode as your primary editor you can use tasks to perform various local actions
+      * Examples:
+        * ```Press Ctrl+P, then type 'task .'``` - Runs complete build (all tasks)
+        * ```Press Ctrl+P, then type 'task Test'``` - Invokes all Pester Unit Tests
+        * ```Press Ctrl+P, then type 'task Analyze'``` - Invokes Script Analyzer checks
+        * ```Press Ctrl+P, then type 'task DevCC'``` - Generates generate xml file to graphically display code coverage in VSCode using [Coverage Gutters](https://marketplace.visualstudio.com/items?itemName=ryanluker.vscode-coverage-gutters)
+1. *The comment based help in your functions will be used to generate/update markdown docs for your module in the docs folder.*
 1. Upload to your desired repository which now has a triggered/monitored build action.
 1. Evaluate results of your build and display your Azure Pipelines badge proudly!
 

diff --git a/docs/Catesta-FAQ.md b/docs/Catesta-FAQ.md
@@ -42,3 +42,20 @@ PSUseToExportFieldsInManifest       Warning      ActionsTes 75    Do not use wil
                                                  t.psd1           Explicitly specify a list for CmdletsToExport.
 PSUseToExportFieldsInManifest       Warning      ActionsTes 81    Do not use wildcard or $null in this field.
 ```
+
+### How does Catesta handle help creation?
+
+Catesta leverages [platyPS](https://github.com/PowerShell/platyPS) for external help creation.
+
+The *source of truth* for all help in your project is derived from the comment base help in your public functions.
+  * Functions located inside your public folder.
+
+During the help generation process your functions in the public folders are evaluated and the comment based help is used to create markdown files using [platyPS](https://github.com/PowerShell/platyPS). Once these markdown files are created, platyPS is used again to craft an external xml based help filed (common for PowerShell use).
+
+During the build process all functions are combined into the .psm1. All comment based help is stripped at this time and replaced with a reference to the external xml file.
+
+Your comment based help continues to persist in your public functions folder and remains the source of truth. If help is updated or changed, it will be updated on the next build that you run in the same fashion.
+
+Help workflow:
+
+Craft excellent comment based help -> Run build -> markdown files generated -> xml file generated from markdown -> functions combined to psm1 -> comment based help stripped in psm1 and replaced with reference to external xml file -> parent level markdown docs updated for easy documentation reading in markdown on your repo.
diff --git a/docs/Catesta-GHActions.md b/docs/Catesta-GHActions.md
@@ -37,6 +37,13 @@ Scaffolds a new PowerShell module project intended for CI/CD workflow using  [Gi
         * [M] MacOS
 1. Write a kick-ass module (the hardest part)
     * All build testing can be done locally by navigating to src and running ```Invoke-Build```
+    * If using VSCode as your primary editor you can use tasks to perform various local actions
+      * Examples:
+        * ```Press Ctrl+P, then type 'task .'``` - Runs complete build (all tasks)
+        * ```Press Ctrl+P, then type 'task Test'``` - Invokes all Pester Unit Tests
+        * ```Press Ctrl+P, then type 'task Analyze'``` - Invokes Script Analyzer checks
+        * ```Press Ctrl+P, then type 'task DevCC'``` - Generates generate xml file to graphically display code coverage in VSCode using [Coverage Gutters](https://marketplace.visualstudio.com/items?itemName=ryanluker.vscode-coverage-gutters)
+1. *The comment based help in your functions will be used to generate/update markdown docs for your module in the docs folder.*
 1. Upload to your desired repository which now has a triggered/monitored build action.
 1. Evaluate results of your build and display your GitHub Actions badge proudly!
 

diff --git a/docs/Catesta.md b/docs/Catesta.md
@@ -2,7 +2,7 @@
 Module Name: Catesta
 Module Guid: 6796b193-9013-468a-b022-837749af2d06
 Download Help Link: NA
-Help Version: 0.9.0
+Help Version: 0.9.7
 Locale: en-US
 ---