Overwrite docs (#73)

Updated New-MarkdownHelp with force parameter.

This is a signed version of #67 

## Description
New-MarkdownHelp should always overwrite new old markdown pages.
If this is not suitable a parameter should be added to be able to force
it.

## Related Issue
<!--- This project only accepts pull requests related to open issues -->
<!--- If suggesting a new feature or change, please discuss it in an
issue first -->
<!--- If fixing a bug, there should be an issue describing it with steps
to reproduce -->
<!--- Please link to the issue here: -->

## Motivation and Context
<!--- Why is this change required? What problem does it solve? -->
This allows the comment based help to be the source of truth.

## How Has This Been Tested?
<!--- Please describe in detail how you tested your changes. -->
<!--- Include details of your testing environment, and the tests you ran
to -->
<!--- see how your change affects other areas of the code, etc. -->

## Checklist:
<!--- Go over all the following points, and put an `x` in all the boxes
that apply. -->
<!--- If you're unsure about any of these, don't hesitate to ask. We're
here to help! -->
- [ ] My code follows the code style of this project.
- [ ] I have updated the documentation accordingly.
- [ ] I have added this change to the CHANGELOG.md.
- [ ] I have read the **CONTRIBUTING** document.
- [ ] I have added tests to cover my changes.
- [ ] All new and existing tests passed.

---------

Co-authored-by: Dylan Prins <8777848+Dylan-Prins@users.noreply.github.com>

Author: HeyItsGilbert

.markdownlint.json

@@ -2,5 +2,9 @@
   "$schema": "https://raw.githubusercontent.com/DavidAnson/vscode-markdownlint/refs/heads/main/markdownlint-config-schema.json",
   "MD024": {
     "siblings_only": true
+  },
+  "MD013": {
+    "code_blocks": false,
+    "tables": false
   }
 }

CHANGELOG.md

@@ -7,9 +7,13 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 
 ## Unreleased
 
+### Breaking Changes
+
 - [**#71**](https://github.com/psake/PowerShellBuild/pull/71) Compiled modules
   are now explicitly created as UTF-8 files.
-
+- [**#67**](https://github.com/psake/PowerShellBuild/pull/67) You can now
+  overwrite existing markdown files using `$PSBPreference.Docs.Overwrite` and
+  setting it to `$true`.
 
 ## [0.6.2] 2024-10-06
 

PowerShellBuild/IB.tasks.ps1

@@ -121,6 +121,7 @@ task GenerateMarkdown -if (. $genMarkdownPreReqs) StageFiles,{
         ModuleName = $PSBPreference.General.ModuleName
         DocsPath   = $PSBPreference.Docs.RootDir
         Locale     = $PSBPreference.Help.DefaultLocale
+        Overwrite  = $PSBPreference.Docs.Overwrite
     }
     Build-PSBuildMarkdown @buildMDParams
 }

PowerShellBuild/Public/Build-PSBuildMarkdown.ps1

@@ -12,6 +12,8 @@ function Build-PSBuildMarkdown {
         The path where PlatyPS markdown docs will be saved.
     .PARAMETER Locale
         The locale to save the markdown docs.
+    .PARAMETER Overwrite
+        Overwrite existing markdown files and use comment based help as the source of truth.
     .EXAMPLE
         PS> Build-PSBuildMarkdown -ModulePath ./output/MyModule/0.1.0 -ModuleName MyModule -DocsPath ./docs -Locale en-US
 
@@ -29,7 +31,10 @@ function Build-PSBuildMarkdown {
         [string]$DocsPath,
 
         [parameter(Mandatory)]
-        [string]$Locale
+        [string]$Locale,
+
+        [parameter(Mandatory)]
+        [bool]$Overwrite
     )
 
     $moduleInfo = Import-Module "$ModulePath/$ModuleName.psd1" -Global -Force -PassThru
@@ -52,13 +57,20 @@ function Build-PSBuildMarkdown {
 
         # ErrorAction set to SilentlyContinue so this command will not overwrite an existing MD file.
         $newMDParams = @{
-            Module         = $ModuleName
-            Locale         = $Locale
-            OutputFolder   = [IO.Path]::Combine($DocsPath, $Locale)
-            ErrorAction    = 'SilentlyContinue'
-            Verbose        = $VerbosePreference
+            Module = $ModuleName
+            Locale = $Locale
+            OutputFolder = [IO.Path]::Combine($DocsPath, $Locale)
+            ErrorAction = 'SilentlyContinue'
+            Verbose = $VerbosePreference
+            Force = $Overwrite
+        }
+        if ($Overwrite) {
+            $newMDParams.Add('Force', $true)
+            $newMDParams.Remove('ErrorAction')
         }
         New-MarkdownHelp @newMDParams > $null
+    } catch {
+        Write-Error "Failed to generate markdown help. : $_"
     } finally {
         Remove-Module $moduleName
     }

PowerShellBuild/build.properties.ps1

@@ -1,6 +1,6 @@
 BuildHelpers\Set-BuildEnvironment -Force
 
-$outDir        = [IO.Path]::Combine($env:BHProjectPath, 'Output')
+$outDir = [IO.Path]::Combine($env:BHProjectPath, 'Output')
 $moduleVersion = (Import-PowerShellDataFile -Path $env:BHPSModuleManifest).ModuleVersion
 
 [ordered]@{
@@ -97,7 +97,7 @@ $moduleVersion = (Import-PowerShellDataFile -Path $env:BHPSModuleManifest).Modul
             OutputFileFormat = 'JaCoCo'
         }
     }
-    Help  = @{
+    Help = @{
         # Path to updateable help CAB
         UpdatableHelpOutDir = [IO.Path]::Combine($outDir, 'UpdatableHelp')
 
@@ -111,6 +111,9 @@ $moduleVersion = (Import-PowerShellDataFile -Path $env:BHPSModuleManifest).Modul
     Docs = @{
         # Directory PlatyPS markdown documentation will be saved to
         RootDir = [IO.Path]::Combine($env:BHProjectPath, 'docs')
+
+        # Whether to overwrite existing markdown files and use comment based help as the source of truth
+        Overwrite = $false
     }
     Publish = @{
         # PowerShell repository name to publish modules to

PowerShellBuild/psakeFile.ps1

@@ -128,6 +128,7 @@ task GenerateMarkdown -depends StageFiles -precondition $genMarkdownPreReqs {
         ModuleName = $PSBPreference.General.ModuleName
         DocsPath   = $PSBPreference.Docs.RootDir
         Locale     = $PSBPreference.Help.DefaultLocale
+        Overwrite  = $PSBPreference.Docs.Overwrite
     }
     Build-PSBuildMarkdown @buildMDParams
 } -description 'Generates PlatyPS markdown files from module help'