Skip to content

Commit b3d1110

Browse files
KoenZomersKoenZomers
authored
Merge pull request #3455 from KoenZomers/dev
Fixing documentation update to generate cmdlet pages for aliases on cmdlets
2 parents 249ced4 + 103096f commit b3d1110

File tree

4 files changed

+60
-47
lines changed

4 files changed

+60
-47
lines changed

‎build/Build-HelpFile.ps1

-39
Original file line numberDiff line numberDiff line change
@@ -6,45 +6,6 @@ if($IsLinux -or $isMacOS)
66
$destinationFolder = "$documentsFolder/PowerShell/Modules/PnP.PowerShell"
77
}
88

9-
Try {
10-
Write-Host "Generating documentation files for alias cmdlets" -ForegroundColor Yellow
11-
# Load the Module in a new PowerShell session
12-
$scriptBlock = {
13-
$documentsFolder = [environment]::getfolderpath("mydocuments")
14-
if($IsLinux -or $isMacOS)
15-
{
16-
$destinationFolder = "$documentsFolder/.local/share/powershell/Modules/PnP.PowerShell"
17-
} else {
18-
$destinationFolder = "$documentsFolder/PowerShell/Modules/PnP.PowerShell"
19-
}
20-
$pnpDllLocation = "$destinationFolder/Core/PnP.PowerShell.dll"
21-
22-
Write-Host "Importing PnP PowerShell assembly from $pnpDllLocation"
23-
Import-Module -Name $pnpDllLocation -DisableNameChecking -Force
24-
Write-Host "Import PnP PowerShell successful"
25-
$cmdlets = Get-Command -Module PnP.PowerShell | Where-Object CommandType -eq "Alias" | Select-Object -Property @{N="Alias";E={$_.Name}}, @{N="ReferencedCommand";E={$_.ReferencedCommand.Name}}
26-
$cmdlets
27-
Write-Host "Retrieved alias cmdlets successfully"
28-
}
29-
$aliasCmdlets = Start-ThreadJob -ScriptBlock $scriptBlock | Receive-Job -Wait
30-
31-
Write-Host " - $($aliasCmdlets.Length) found" -ForegroundColor Yellow
32-
33-
$aliasTemplatePageContent = Get-Content -Path "../pages/cmdlets/alias.md" -Raw
34-
35-
ForEach($aliasCmdlet in $aliasCmdlets)
36-
{
37-
$destinationFileName = "./../documentation/$($aliasCmdlet.Alias).md"
38-
39-
Write-Host " - Creating page for $($aliasCmdlet.Alias) being an alias for $($aliasCmdlet.ReferencedCommand) as $destinationFileName" -ForegroundColor Yellow
40-
$aliasTemplatePageContent.Replace("%%cmdletname%%", $aliasCmdlet.Alias).Replace("%%referencedcmdletname%%", $aliasCmdlet.ReferencedCommand) | Out-File $destinationFileName -Force
41-
}
42-
}
43-
Catch {
44-
Write-Host "Error: Cannot generate alias documentation files"
45-
Write-Host $_
46-
}
47-
489
$tempFolder = [System.IO.Path]::GetTempPath()
4910

5011
$runsInAction = $("$env:RUNSINACTION")

‎pages/Build-Site.ps1

+54-5
Original file line numberDiff line numberDiff line change
@@ -63,20 +63,57 @@ class FrontMatters {
6363

6464
$fm = New-Object -TypeName FrontMatters
6565

66+
$aliasCmdletsCount = 0
67+
$aliasCmdlets = @()
68+
Try {
69+
Write-Host "Generating documentation files for alias cmdlets" -ForegroundColor Yellow
70+
# Load the Module in a new PowerShell session
71+
$scriptBlock = {
72+
Write-Host "Installing latest nightly of PnP PowerShell"
73+
Install-Module PnP.PowerShell -AllowPrerelease -Force
74+
75+
Write-Host "Retrieving PnP PowerShell alias cmdlets"
76+
$cmdlets = Get-Command -Module PnP.PowerShell | Where-Object CommandType -eq "Alias" | Select-Object -Property @{N="Alias";E={$_.Name}}, @{N="ReferencedCommand";E={$_.ReferencedCommand.Name}}
77+
$cmdlets
78+
Write-Host "$($cmdlets.Length) alias cmdlets retrieved"
79+
}
80+
$aliasCmdlets = Start-ThreadJob -ScriptBlock $scriptBlock | Receive-Job -Wait
81+
82+
$aliasCmdletsCount = $aliasCmdlets.Length
83+
84+
Write-Host "- Retrieving alias template page"
85+
$aliasTemplatePageContent = Get-Content -Path "./dev/pages/cmdlets/alias.md" -Raw
86+
87+
ForEach($aliasCmdlet in $aliasCmdlets)
88+
{
89+
$destinationFileName = "./dev/documentation/$($aliasCmdlet.Alias).md"
90+
91+
Write-Host "- Creating page for $($aliasCmdlet.Alias) being an alias for $($aliasCmdlet.ReferencedCommand) as $destinationFileName" -ForegroundColor Yellow
92+
$aliasTemplatePageContent.Replace("%%cmdletname%%", $aliasCmdlet.Alias).Replace("%%referencedcmdletname%%", $aliasCmdlet.ReferencedCommand) | Out-File $destinationFileName -Force
93+
}
94+
}
95+
Catch {
96+
Write-Host "Error: Cannot generate alias documentation files"
97+
Write-Host $_
98+
}
99+
100+
Write-Host "Copying documentation files to page cmdlets"
101+
66102
Copy-Item -Path "./dev/documentation/*.md" -Destination "./dev/pages/cmdlets" -Force
67103

68104
foreach ($nightlycmdlet in $nightlycmdlets) {
69105
if (!$releasedcmdlets.Contains($nightlycmdlet)) {
70-
Copy-Item "./dev/documentation/$nightlycmdlet" -Destination "./dev/pages/cmdlets" -Force
106+
Copy-Item "./dev/documentation/$nightlycmdlet" -Destination "./dev/pages/cmdlets" -Force | Out-Null
71107
# update the document to state it's only available in the nightly build
72108
$header = $fm.GetHeader("./dev/pages/cmdlets/$nightlycmdlet")
73109
$header["tags"] = "Available in the current Nightly Release only."
74-
Write-Host "Writing $nightlycmdlet"
110+
#Write-Host "Writing $nightlycmdlet"
75111
$fm.WriteHeader("./dev/pages/cmdlets/$nightlycmdlet",$header)
76112
}
77113
}
78114

79115
# Generate cmdlet toc
116+
Write-Host "Retrieving all cmdlet pages"
80117

81118
$cmdletPages = Get-ChildItem -Path "./dev/pages/cmdlets/*.md" -Exclude "index.md","alias.md"
82119
$toc = ""
@@ -88,13 +125,17 @@ $toc | Out-File "./dev/pages/cmdlets/toc.yml" -Force
88125

89126
# Generate cmdlet index page
90127

128+
Write-Host "Creating cmdlets index page"
129+
91130
$cmdletIndexPageContent = Get-Content -Path "./dev/pages/cmdlets/index.md" -Raw
92-
$cmdletIndexPageContent = $cmdletIndexPageContent.Replace("%%cmdletcount%%", $cmdletPages.Length)
131+
$cmdletIndexPageContent = $cmdletIndexPageContent.Replace("%%cmdletcount%%", $cmdletPages.Length - $aliasCmdletsCount)
93132

94133
$cmdletIndexPageList = ""
95134
$previousCmdletVerb = ""
96135
foreach ($cmdletPage in $cmdletPages)
97136
{
137+
Write-Host "- $($cmdletPage.Name)"
138+
98139
# Define the verb of the cmdlet
99140
if($cmdletPage.BaseName.Contains("-"))
100141
{
@@ -117,9 +158,17 @@ foreach ($cmdletPage in $cmdletPages)
117158
# Check if the cmdlet only exists in the nightly build
118159
if (!$releasedcmdlets.Contains($cmdletPage.Name))
119160
{
120-
# Add an asterisk to the cmdlet name if it's only available in the nightly build
121-
$cmdletIndexPageList = $cmdletIndexPageList + "*"
161+
# Add a 1 to the cmdlet name if it's only available in the nightly build
162+
$cmdletIndexPageList = $cmdletIndexPageList + " <sup>1</sup>"
122163
}
164+
165+
# Check if the cmdlet is an alias
166+
if ($aliasCmdlets.Alias -contains $cmdletPage.BaseName)
167+
{
168+
# Add a 2 to the cmdlet name if it's an alias
169+
$cmdletIndexPageList = $cmdletIndexPageList + " <sup>2</sup>"
170+
}
171+
123172
$cmdletIndexPageList = $cmdletIndexPageList + "`n"
124173

125174
if($cmdletVerb -ne "")

‎pages/cmdlets/alias.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -10,8 +10,8 @@ online version: https://pnp.github.io/powershell/cmdlets/%%cmdletname%%.html
1010
# %%cmdletname%%
1111

1212
## SYNOPSIS
13-
This is an alias for [%%referencedcmdletname%%](./%%referencedcmdletname%%.md)
13+
This is an alias for [%%referencedcmdletname%%](./%%referencedcmdletname%%.md). Please update your scripts to use this cmdlet instead as it may be removed in a future update.
1414

1515
## RELATED LINKS
1616

17-
[Microsoft 365 Patterns and Practices](https://aka.ms/m365pnp)
17+
[Microsoft 365 Patterns and Practices](https://aka.ms/m365pnp)

‎pages/cmdlets/index.md

+4-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,8 @@
11
# PnP PowerShell cmdlets
22

3-
PnP PowerShell exists out of %%cmdletcount%% cmdlets which can help you in setting up, configuring, maintaining and using various Microsoft 365 products from one single connection. Each of the cmdlets is documented to aid in learning how to use it. Find the available cmdlets below. Cmdlets marked with asterisk ( * ) are only available in the latest nightly build. All the others can also be used using the latest stable release.
3+
PnP PowerShell exists out of %%cmdletcount%% cmdlets which can help you in setting up, configuring, maintaining and using various Microsoft 365 products from one single connection. Each of the cmdlets is documented to aid in learning how to use it. Find the available cmdlets below.
4+
5+
<sup>1</sup>: Only available in the latest nightly build. All the others can also be used using the latest stable release.
6+
<sup>2</sup>: Cmdlet is an alias of another cmdlet, used to provide backwards compatibility.
47

58
%%cmdletlisting%%

0 commit comments

Comments
 (0)