|
7 | 7 | Builds a module. |
8 | 8 | #> |
9 | 9 | [CmdletBinding()] |
10 | | - [Diagnostics.CodeAnalysis.SuppressMessageAttribute( |
11 | | - 'PSReviewUnusedParameter', '', Scope = 'Function', |
12 | | - Justification = 'LogGroup - Scoping affects the variables line of sight.' |
13 | | - )] |
14 | 10 | [Diagnostics.CodeAnalysis.SuppressMessageAttribute( |
15 | 11 | 'PSAvoidUsingWriteHost', '', Scope = 'Function', |
16 | 12 | Justification = 'Want to just write to the console, not the pipeline.' |
17 | 13 | )] |
18 | | - #Requires -Modules GitHub |
19 | | - #Requires -Modules Utilities |
20 | 14 | param( |
21 | 15 | # Name of the module. |
22 | 16 | [Parameter(Mandatory)] |
|
35 | 29 | [string] $DocsOutputFolderPath |
36 | 30 | ) |
37 | 31 |
|
38 | | - LogGroup "Documenting module [$ModuleName]" { |
39 | | - Write-Host "Source path: [$ModuleSourceFolderPath]" |
40 | | - if (-not (Test-Path -Path $ModuleSourceFolderPath)) { |
41 | | - Write-Error "Source folder not found at [$ModuleSourceFolderPath]" |
42 | | - exit 1 |
43 | | - } |
44 | | - $moduleSourceFolder = Get-Item -Path $ModuleSourceFolderPath |
45 | | - Write-Host "Module source folder: [$moduleSourceFolder]" |
46 | | - |
47 | | - $moduleOutputFolder = New-Item -Path $ModulesOutputFolderPath -Name $ModuleName -ItemType Directory -Force |
48 | | - Write-Host "Module output folder: [$moduleOutputFolder]" |
| 32 | + Write-Host "::group::Documenting module [$ModuleName]" |
| 33 | + [pscustomobject]@{ |
| 34 | + ModuleName = $ModuleName |
| 35 | + ModuleSourceFolderPath = $ModuleSourceFolderPath |
| 36 | + ModulesOutputFolderPath = $ModulesOutputFolderPath |
| 37 | + DocsOutputFolderPath = $DocsOutputFolderPath |
| 38 | + } | Format-List | Out-String |
49 | 39 |
|
50 | | - $docsOutputFolder = New-Item -Path $DocsOutputFolderPath -ItemType Directory -Force |
51 | | - Write-Host "Docs output folder: [$docsOutputFolder]" |
| 40 | + if (-not (Test-Path -Path $ModuleSourceFolderPath)) { |
| 41 | + Write-Error "Source folder not found at [$ModuleSourceFolderPath]" |
| 42 | + exit 1 |
52 | 43 | } |
| 44 | + $moduleSourceFolder = Get-Item -Path $ModuleSourceFolderPath |
| 45 | + $moduleOutputFolder = New-Item -Path $ModulesOutputFolderPath -Name $ModuleName -ItemType Directory -Force |
| 46 | + $docsOutputFolder = New-Item -Path $DocsOutputFolderPath -ItemType Directory -Force |
53 | 47 |
|
54 | | - LogGroup 'Build docs - Generate markdown help' { |
55 | | - Add-PSModulePath -Path (Split-Path -Path $ModuleOutputFolder -Parent) |
56 | | - $ModuleName | Remove-Module -Force -ErrorAction SilentlyContinue |
57 | | - Import-PSModule -Path $ModuleOutputFolder -ModuleName $ModuleName |
58 | | - Write-Host ($ModuleName | Get-Module) |
59 | | - $null = New-MarkdownHelp -Module $ModuleName -OutputFolder $DocsOutputFolder -Force -Verbose |
| 48 | + Write-Host '::group::Build docs - Generate markdown help - Raw' |
| 49 | + Install-PSModule -Path $ModuleOutputFolder |
| 50 | + Write-Host ($ModuleName | Get-Module) |
| 51 | + $null = New-MarkdownHelp -Module $ModuleName -OutputFolder $DocsOutputFolder -Force -Verbose |
| 52 | + Get-ChildItem -Path $DocsOutputFolder -Recurse -Force -Include '*.md' | ForEach-Object { |
| 53 | + $fileName = $_.Name |
| 54 | + Write-Host "::group:: - [$fileName]" |
| 55 | + Show-FileContent -Path $_ |
60 | 56 | } |
61 | 57 |
|
62 | | - LogGroup 'Build docs - Fix markdown code blocks' { |
63 | | - Get-ChildItem -Path $DocsOutputFolder -Recurse -Force -Include '*.md' | ForEach-Object { |
64 | | - $content = Get-Content -Path $_.FullName |
65 | | - $fixedOpening = $false |
66 | | - $newContent = @() |
67 | | - foreach ($line in $content) { |
68 | | - if ($line -match '^```$' -and -not $fixedOpening) { |
69 | | - $line = $line -replace '^```$', '```powershell' |
70 | | - $fixedOpening = $true |
71 | | - } elseif ($line -match '^```.+$') { |
72 | | - $fixedOpening = $true |
73 | | - } elseif ($line -match '^```$') { |
74 | | - $fixedOpening = $false |
75 | | - } |
76 | | - $newContent += $line |
| 58 | + Write-Host '::group::Build docs - Fix markdown code blocks' |
| 59 | + Get-ChildItem -Path $DocsOutputFolder -Recurse -Force -Include '*.md' | ForEach-Object { |
| 60 | + $content = Get-Content -Path $_.FullName |
| 61 | + $fixedOpening = $false |
| 62 | + $newContent = @() |
| 63 | + foreach ($line in $content) { |
| 64 | + if ($line -match '^```$' -and -not $fixedOpening) { |
| 65 | + $line = $line -replace '^```$', '```powershell' |
| 66 | + $fixedOpening = $true |
| 67 | + } elseif ($line -match '^```.+$') { |
| 68 | + $fixedOpening = $true |
| 69 | + } elseif ($line -match '^```$') { |
| 70 | + $fixedOpening = $false |
77 | 71 | } |
78 | | - $newContent | Set-Content -Path $_.FullName |
| 72 | + $newContent += $line |
79 | 73 | } |
| 74 | + $newContent | Set-Content -Path $_.FullName |
80 | 75 | } |
81 | 76 |
|
82 | | - LogGroup 'Build docs - Fix markdown escape characters' { |
83 | | - Get-ChildItem -Path $DocsOutputFolder -Recurse -Force -Include '*.md' | ForEach-Object { |
84 | | - $content = Get-Content -Path $_.FullName -Raw |
85 | | - $content = $content -replace '\\`', '`' |
86 | | - $content = $content -replace '\\\[', '[' |
87 | | - $content = $content -replace '\\\]', ']' |
88 | | - $content = $content -replace '\\\<', '<' |
89 | | - $content = $content -replace '\\\>', '>' |
90 | | - $content = $content -replace '\\\\', '\' |
91 | | - $content | Set-Content -Path $_.FullName |
92 | | - } |
| 77 | + Write-Host '::group::Build docs - Fix markdown escape characters' |
| 78 | + Get-ChildItem -Path $DocsOutputFolder -Recurse -Force -Include '*.md' | ForEach-Object { |
| 79 | + $content = Get-Content -Path $_.FullName -Raw |
| 80 | + $content = $content -replace '\\`', '`' |
| 81 | + $content = $content -replace '\\\[', '[' |
| 82 | + $content = $content -replace '\\\]', ']' |
| 83 | + $content = $content -replace '\\\<', '<' |
| 84 | + $content = $content -replace '\\\>', '>' |
| 85 | + $content = $content -replace '\\\\', '\' |
| 86 | + $content | Set-Content -Path $_.FullName |
93 | 87 | } |
94 | 88 |
|
95 | | - LogGroup 'Build docs - Structure markdown files to match source files' { |
96 | | - $PublicFunctionsFolder = Join-Path $ModuleSourceFolder.FullName 'functions\public' | Get-Item |
97 | | - Get-ChildItem -Path $DocsOutputFolder -Recurse -Force -Include '*.md' | ForEach-Object { |
98 | | - $file = $_ |
99 | | - Write-Host "Processing: $file" |
| 89 | + Write-Host '::group::Build docs - Structure markdown files to match source files' |
| 90 | + $PublicFunctionsFolder = Join-Path $ModuleSourceFolder.FullName 'functions\public' | Get-Item |
| 91 | + Get-ChildItem -Path $DocsOutputFolder -Recurse -Force -Include '*.md' | ForEach-Object { |
| 92 | + $file = $_ |
| 93 | + $relPath = [System.IO.Path]::GetRelativePath($DocsOutputFolder.FullName, $file.FullName) |
| 94 | + Write-Host " - $relPath" |
| 95 | + Write-Host " Path: $file" |
100 | 96 |
|
101 | | - # find the source code file that matches the markdown file |
102 | | - $scriptPath = Get-ChildItem -Path $PublicFunctionsFolder -Recurse -Force | Where-Object { $_.Name -eq ($file.BaseName + '.ps1') } |
103 | | - Write-Host "Found script path: $scriptPath" |
104 | | - $docsFilePath = ($scriptPath.FullName).Replace($PublicFunctionsFolder.FullName, $DocsOutputFolder.FullName).Replace('.ps1', '.md') |
105 | | - Write-Host "Doc file path: $docsFilePath" |
106 | | - $docsFolderPath = Split-Path -Path $docsFilePath -Parent |
107 | | - New-Item -Path $docsFolderPath -ItemType Directory -Force |
108 | | - Move-Item -Path $file.FullName -Destination $docsFilePath -Force |
109 | | - } |
110 | | - # Get the MD files that are in the public functions folder and move them to the same place in the docs folder |
111 | | - Get-ChildItem -Path $PublicFunctionsFolder -Recurse -Force -Include '*.md' | ForEach-Object { |
112 | | - $file = $_ |
113 | | - Write-Host "Processing: $file" |
114 | | - $docsFilePath = ($file.FullName).Replace($PublicFunctionsFolder.FullName, $DocsOutputFolder.FullName) |
115 | | - Write-Host "Doc file path: $docsFilePath" |
116 | | - $docsFolderPath = Split-Path -Path $docsFilePath -Parent |
117 | | - New-Item -Path $docsFolderPath -ItemType Directory -Force |
118 | | - Move-Item -Path $file.FullName -Destination $docsFilePath -Force |
119 | | - } |
| 97 | + # find the source code file that matches the markdown file |
| 98 | + $scriptPath = Get-ChildItem -Path $PublicFunctionsFolder -Recurse -Force | Where-Object { $_.Name -eq ($file.BaseName + '.ps1') } |
| 99 | + Write-Host " PS1 path: $scriptPath" |
| 100 | + $docsFilePath = ($scriptPath.FullName).Replace($PublicFunctionsFolder.FullName, $DocsOutputFolder.FullName).Replace('.ps1', '.md') |
| 101 | + Write-Host " MD path: $docsFilePath" |
| 102 | + $docsFolderPath = Split-Path -Path $docsFilePath -Parent |
| 103 | + $null = New-Item -Path $docsFolderPath -ItemType Directory -Force |
| 104 | + Move-Item -Path $file.FullName -Destination $docsFilePath -Force |
120 | 105 | } |
121 | 106 |
|
| 107 | + Write-Host '::group::Build docs - Move markdown files from source files to docs' |
| 108 | + Get-ChildItem -Path $PublicFunctionsFolder -Recurse -Force -Include '*.md' | ForEach-Object { |
| 109 | + $file = $_ |
| 110 | + $relPath = [System.IO.Path]::GetRelativePath($PublicFunctionsFolder.FullName, $file.FullName) |
| 111 | + Write-Host " - $relPath" |
| 112 | + Write-Host " Path: $file" |
| 113 | + |
| 114 | + $docsFilePath = ($file.FullName).Replace($PublicFunctionsFolder.FullName, $DocsOutputFolder.FullName) |
| 115 | + Write-Host " MD path: $docsFilePath" |
| 116 | + $docsFolderPath = Split-Path -Path $docsFilePath -Parent |
| 117 | + $null = New-Item -Path $docsFolderPath -ItemType Directory -Force |
| 118 | + Move-Item -Path $file.FullName -Destination $docsFilePath -Force |
| 119 | + } |
| 120 | + |
| 121 | + Write-Host '────────────────────────────────────────────────────────────────────────────────' |
122 | 122 | Get-ChildItem -Path $DocsOutputFolder -Recurse -Force -Include '*.md' | ForEach-Object { |
123 | 123 | $fileName = $_.Name |
124 | | - $hash = (Get-FileHash -Path $_.FullName -Algorithm SHA256).Hash |
125 | | - LogGroup " - [$fileName] - [$hash]" { |
126 | | - Show-FileContent -Path $_ |
127 | | - } |
| 124 | + Write-Host "::group:: - [$fileName]" |
| 125 | + Show-FileContent -Path $_ |
128 | 126 | } |
129 | 127 | } |
0 commit comments