Skip to content

Commit e6d41ec

Browse files
jakehildrethjakehildreth
authored
Merge pull request #199 from SamErde/se-mkdocs-01
Workflows to generate and publish documentation and online help
2 parents ba514e3 + 1a47001 commit e6d41ec

29 files changed

+970
-76
lines changed

‎.github/workflows/Create External Help.yml‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
name: 📚 Create External Help
2+
3+
on:
4+
pull_request:
5+
#push:
6+
workflow_dispatch:
7+
8+
jobs:
9+
package_help:
10+
# The New-ExternalHelpCab cmdlet uses makecab, which depends on Windows.
11+
runs-on: windows-latest
12+
steps:
13+
- name: ✅ Checkout Repository
14+
uses: actions/checkout@v4
15+
- name: 📁 Display the Path
16+
shell: pwsh
17+
run: echo ${env:PATH}
18+
- name: 🔢 Display the Version
19+
shell: pwsh
20+
run: $PSVersionTable
21+
- name: 📖 Create and Package External PowerShell Help
22+
shell: pwsh
23+
run: |
24+
Install-Module -Name PlatyPS -Scope CurrentUser -Force -SkipPublisherCheck
25+
Import-Module -Name PlatyPS -Force
26+
#Copy-Item ".\Help\en-US\Locksmith-help.xml" ".\Help\en-US"
27+
$params = @{
28+
CabFilesFolder = ".\en-US"
29+
LandingPagePath = ".\Docs\Locksmith.md"
30+
OutputFolder = ".\en-US"
31+
}
32+
New-ExternalHelpCab @params

‎.github/workflows/Deploy MkDocs.yml‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
name: 📖 Deploy MkDocs to GitHub
2+
# Install, build, and deploy MkDocs to GitHub Pages using content from the Docs folder.
3+
4+
on:
5+
push:
6+
branches:
7+
- main # The branch you want to deploy from
8+
paths: # Only deploy MkDocs when the contents of the docs folder change or when this workflow changes.
9+
- 'Docs/**'
10+
- '.github/workflows/Deploy MkDocs.yml'
11+
- './mkdocs.yml'
12+
workflow_dispatch:
13+
14+
jobs:
15+
build:
16+
runs-on: ubuntu-latest
17+
18+
steps:
19+
- name: ✅ Checkout Repository
20+
uses: actions/checkout@v4
21+
22+
- name: 🐍 Setup Python
23+
uses: actions/setup-python@v5
24+
with:
25+
python-version: '3.x' # specify the Python version
26+
27+
- name: ➕ Install Dependencies
28+
run: |
29+
python -m pip install --upgrade pip
30+
pip install mkdocs mkdocs-material
31+
32+
- name: 👷‍♂️ Build & Deploy MkDocs
33+
run: |
34+
mkdocs build
35+
mkdocs gh-deploy --force
36+
37+
# Combine markdown files to create the MkDocs index and the repository readme file.
38+
- name: 📖 Update Index & Readme
39+
shell: pwsh
40+
run: |
41+
Write-Output 'Updating Docs\Index.md & \Readme.md'
42+
Copy-Item ./README.md ./docs/index.md
43+
# [int16]$LineNumber = (Select-String -Path '.\docs\index.md' -Pattern 'Summary' -List).LineNumber + 1
44+
# $IndexTop = Get-Content -Path ./docs/index.md -TotalCount $LineNumber
45+
# $ModuleContent = Get-Content -Path ./docs/Locksmith.md | Select-Object -Skip 12
46+
# $FooterContent = "`n</Details>`n"
47+
# $CombinedContent = $IndexTop + $ModuleContent + $FooterContent
48+
# $CombinedContent | Set-Content -Path ./docs/index.md
49+
# $ModuleContent = $ModuleContent.Replace( '](' , '](./docs/' )
50+
# $CombinedContent = $IndexTop + $ModuleContent
51+
# $CombinedContent | Set-Content -Path ./README.md
52+
# Copy-Item ./docs/index.md ./README.md
53+
54+
# NOTE: git-auto-commit-action only runs on Linux-based platforms.
55+
#- name: 💾 Commit Changes
56+
# uses: stefanzweifel/git-auto-commit-action@v5
57+
# with:
58+
# commit_message: 'Copy MkDocs index to README'
59+
# file_pattern: 'docs/index.md README.md'

‎.readthedocs.yaml‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# https://docs.readthedocs.io/en/stable/config-file/index.html
2+
3+
# .readthedocs.yaml
4+
# Read the Docs configuration file
5+
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
6+
7+
# Required
8+
version: 2
9+
10+
build:
11+
os: ubuntu-22.04
12+
tools:
13+
python: "3.12"
14+
15+
mkdocs:
16+
configuration: mkdocs.yml
17+
18+
python:
19+
install:
20+
- requirements: docs/requirements.txt
21+
22+
# # Build PDF & ePub
23+
formats: all
24+
# - epub
25+
# - pdf

‎Build/MarkdownRepair.ps1‎

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
<#
2+
.SYNOPSIS
3+
Repair PlatyPS generated markdown files.
4+
.NOTES
5+
This file is temporarily required to handle platyPS help generation.
6+
https://github.com/PowerShell/platyPS/issues/595
7+
This is a result of a breaking change introduced in PowerShell 7.4.0:
8+
https://learn.microsoft.com/en-us/powershell/scripting/whats-new/what-s-new-in-powershell-74?view=powershell-7.4
9+
Breaking Changes: Added the ProgressAction parameter to the Common Parameters
10+
modified from source: https://github.com/PowerShell/platyPS/issues/595#issuecomment-1820971702
11+
#>
12+
13+
function Remove-CommonParameterFromMarkdown {
14+
<#
15+
.SYNOPSIS
16+
Remove a PlatyPS generated parameter block.
17+
.DESCRIPTION
18+
Removes parameter block for the provided parameter name from the markdown file provided.
19+
#>
20+
param(
21+
[Parameter(Mandatory)]
22+
[string[]]
23+
$Path,
24+
25+
[Parameter(Mandatory = $false)]
26+
[string[]]
27+
$ParameterName = @('ProgressAction')
28+
)
29+
$ErrorActionPreference = 'Stop'
30+
foreach ($p in $Path) {
31+
$content = (Get-Content -Path $p -Raw).TrimEnd()
32+
$updateFile = $false
33+
foreach ($param in $ParameterName) {
34+
if (-not ($Param.StartsWith('-'))) {
35+
$param = "-$($param)"
36+
}
37+
# Remove the parameter block
38+
$pattern = "(?m)^### $param\r?\n[\S\s]*?(?=#{2,3}?)"
39+
$newContent = $content -replace $pattern, ''
40+
# Remove the parameter from the syntax block
41+
$pattern = " \[$param\s?.*?]"
42+
$newContent = $newContent -replace $pattern, ''
43+
if ($null -ne (Compare-Object -ReferenceObject $content -DifferenceObject $newContent)) {
44+
Write-Verbose "Added $param to $p"
45+
# Update file content
46+
$content = $newContent
47+
$updateFile = $true
48+
}
49+
}
50+
# Save file if content has changed
51+
if ($updateFile) {
52+
$newContent | Out-File -Encoding utf8 -FilePath $p
53+
Write-Verbose "Updated file: $p"
54+
}
55+
}
56+
return
57+
}
58+
59+
function Add-MissingCommonParameterToMarkdown {
60+
param(
61+
[Parameter(Mandatory)]
62+
[string[]]
63+
$Path,
64+
65+
[Parameter(Mandatory = $false)]
66+
[string[]]
67+
$ParameterName = @('ProgressAction')
68+
)
69+
$ErrorActionPreference = 'Stop'
70+
foreach ($p in $Path) {
71+
$content = (Get-Content -Path $p -Raw).TrimEnd()
72+
$updateFile = $false
73+
foreach ($NewParameter in $ParameterName) {
74+
if (-not ($NewParameter.StartsWith('-'))) {
75+
$NewParameter = "-$($NewParameter)"
76+
}
77+
$pattern = '(?m)^This cmdlet supports the common parameters:(.+?)\.'
78+
$replacement = {
79+
$Params = $_.Groups[1].Captures[0].ToString() -split ' '
80+
$CommonParameters = @()
81+
foreach ($CommonParameter in $Params) {
82+
if ($CommonParameter.StartsWith('-')) {
83+
if ($CommonParameter.EndsWith(',')) {
84+
$CleanParam = $CommonParameter.Substring(0, $CommonParameter.Length - 1)
85+
} elseif ($p.EndsWith('.')) {
86+
$CleanParam = $CommonParameter.Substring(0, $CommonParameter.Length - 1)
87+
} else {
88+
$CleanParam = $CommonParameter
89+
}
90+
$CommonParameters += $CleanParam
91+
}
92+
}
93+
if ($NewParameter -notin $CommonParameters) {
94+
$CommonParameters += $NewParameter
95+
}
96+
$CommonParameters[-1] = "and $($CommonParameters[-1]). "
97+
return 'This cmdlet supports the common parameters: ' + (($CommonParameters | Sort-Object) -join ', ')
98+
}
99+
$newContent = $content -replace $pattern, $replacement
100+
if ($null -ne (Compare-Object -ReferenceObject $content -DifferenceObject $newContent)) {
101+
Write-Verbose "Added $NewParameter to $p"
102+
$updateFile = $true
103+
$content = $newContent
104+
}
105+
}
106+
# Save file if content has changed
107+
if ($updateFile) {
108+
$newContent | Out-File -Encoding utf8 -FilePath $p
109+
Write-Verbose "Updated file: $p"
110+
}
111+
}
112+
return
113+
}
114+
115+
function Repair-PlatyPSMarkdown {
116+
param(
117+
[Parameter(Mandatory)]
118+
[string[]]
119+
$Path,
120+
121+
[Parameter()]
122+
[string[]]
123+
$ParameterName = @('ProgressAction')
124+
)
125+
$ErrorActionPreference = 'Stop'
126+
$Parameters = @{
127+
Path = $Path
128+
ParameterName = $ParameterName
129+
}
130+
$null = Remove-CommonParameterFromMarkdown @Parameters
131+
$null = Add-MissingCommonParameterToMarkdown @Parameters
132+
return
133+
}

‎Build/Write-HelpOutDocs.ps1‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
function Write-HelpOutDocs {
2+
<#
3+
.SYNOPSIS
4+
Write module documentation using the HelpOut module.
5+
6+
.DESCRIPTION
7+
Writes module documentation using the HelpOut module. This functions generates the markdown and MAML help files from
8+
comment-based help in each of the functions. It will also create the external help cab file.
9+
10+
.EXAMPLE
11+
Write-HelpOutDocs
12+
13+
Does what it says on the tin.
14+
15+
#>
16+
[CmdletBinding()]
17+
param ()
18+
19+
$ModuleName = 'Locksmith'
20+
21+
# Remove the module from the current session to ensure we are working with the current source version.
22+
Remove-Module -Name $ModuleName -Force -ErrorAction SilentlyContinue
23+
24+
# Get the path to the module manifest. Check for either PSScriptRoot (if running from a script) or PWD (if running from the console).
25+
$ModulePath = if ($PSScriptRoot) {
26+
# If the $PSScriptRoot variable exists, check if you are in the build folder or the module folder.
27+
if ( (Split-Path -Path $PSScriptRoot -Leaf) -eq 'Build' ) {
28+
Split-Path -Path $PSScriptRoot -Parent
29+
} elseif ( (Split-Path -Path $PSScriptRoot -Leaf) -match $ModuleName ) {
30+
$PSScriptRoot
31+
} else {
32+
throw 'Failed to determine module manifest path. Please ensure you are in the module or build folder.'
33+
}
34+
} else {
35+
# If the $PSScriptRoot variable does not exist, check if you are in the build folder or the module folder.
36+
if ( (Split-Path -Path $PWD.Path -Leaf) -eq 'Build' ) {
37+
Split-Path -Path $PWD -Parent
38+
} elseif ( (Split-Path -Path $pwd -Leaf) -match $ModuleName ) {
39+
$PWD
40+
} else {
41+
throw 'Failed to determine module manifest path. Please ensure you are in the module or build folder.'
42+
}
43+
}
44+
45+
# All of the above is fun, but is largely not needed if you just run the script file instead of pasting the code into the console.
46+
$ModuleManifestPath = Join-Path -Path $ModulePath -ChildPath "${ModuleName}.psd1"
47+
48+
try {
49+
Import-Module ServerManager -ErrorAction SilentlyContinue -WarningAction SilentlyContinue | Out-Null
50+
Import-Module $ModuleManifestPath
51+
} catch {
52+
throw "Failed to import module manifest at $ModuleManifestPath. $_"
53+
}
54+
55+
Save-MarkdownHelp -Module Locksmith -ExcludeFile @('CODE_OF_CONDUCT.md', 'CONTRIBUTING.md', 'TSS Specs.md')
56+
Save-MAML -Module Locksmith
57+
58+
$params = @{
59+
CabFilesFolder = "$PSScriptRoot\..\en-US"
60+
LandingPagePath = "$PSScriptRoot\..\docs\README.md"
61+
OutputFolder = "$PSScriptRoot\..\en-US"
62+
}
63+
New-ExternalHelpCab @params
64+
65+
}
66+
67+
Write-HelpOutDocs

0 commit comments

Comments
 (0)