Fixing documentation update to generate cmdlet pages for aliases on cmdlets

build/Build-HelpFile.ps1

@@ -6,45 +6,6 @@ if($IsLinux -or $isMacOS)
 	$destinationFolder = "$documentsFolder/PowerShell/Modules/PnP.PowerShell"
 }
 
-Try {
-	Write-Host "Generating documentation files for alias cmdlets" -ForegroundColor Yellow
-	# Load the Module in a new PowerShell session
-	$scriptBlock = {
-		$documentsFolder = [environment]::getfolderpath("mydocuments")
-		if($IsLinux -or $isMacOS)
-		{
-			$destinationFolder = "$documentsFolder/.local/share/powershell/Modules/PnP.PowerShell"
-		} else {
-			$destinationFolder = "$documentsFolder/PowerShell/Modules/PnP.PowerShell"
-		}
-		$pnpDllLocation = "$destinationFolder/Core/PnP.PowerShell.dll"
-
-		Write-Host "Importing PnP PowerShell assembly from $pnpDllLocation"
-		Import-Module -Name $pnpDllLocation -DisableNameChecking -Force
-  		Write-Host "Import PnP PowerShell successful"
-		$cmdlets = Get-Command -Module PnP.PowerShell | Where-Object CommandType -eq "Alias" | Select-Object -Property @{N="Alias";E={$_.Name}}, @{N="ReferencedCommand";E={$_.ReferencedCommand.Name}}
-		$cmdlets
-  		Write-Host "Retrieved alias cmdlets successfully"
-	}
-	$aliasCmdlets = Start-ThreadJob -ScriptBlock $scriptBlock | Receive-Job -Wait
-
-	Write-Host "  - $($aliasCmdlets.Length) found" -ForegroundColor Yellow
-
-	$aliasTemplatePageContent = Get-Content -Path "../pages/cmdlets/alias.md" -Raw
-
-	ForEach($aliasCmdlet in $aliasCmdlets)
-	{
-		$destinationFileName = "./../documentation/$($aliasCmdlet.Alias).md"
-
-		Write-Host "    - Creating page for $($aliasCmdlet.Alias) being an alias for $($aliasCmdlet.ReferencedCommand) as $destinationFileName" -ForegroundColor Yellow
-		$aliasTemplatePageContent.Replace("%%cmdletname%%", $aliasCmdlet.Alias).Replace("%%referencedcmdletname%%", $aliasCmdlet.ReferencedCommand) | Out-File $destinationFileName -Force
-	}
-}
-Catch {
-	Write-Host "Error: Cannot generate alias documentation files"
-	Write-Host $_
-}
-
 $tempFolder = [System.IO.Path]::GetTempPath()
 
 $runsInAction = $("$env:RUNSINACTION")

pages/Build-Site.ps1

@@ -63,20 +63,57 @@ class FrontMatters {
 
 $fm = New-Object -TypeName FrontMatters
 
+$aliasCmdletsCount = 0
+$aliasCmdlets = @()
+Try {
+	Write-Host "Generating documentation files for alias cmdlets" -ForegroundColor Yellow
+	# Load the Module in a new PowerShell session
+	$scriptBlock = {
+		Write-Host "Installing latest nightly of PnP PowerShell"
+  		Install-Module PnP.PowerShell -AllowPrerelease -Force
+
+  		Write-Host "Retrieving PnP PowerShell alias cmdlets"
+		$cmdlets = Get-Command -Module PnP.PowerShell | Where-Object CommandType -eq "Alias" | Select-Object -Property @{N="Alias";E={$_.Name}}, @{N="ReferencedCommand";E={$_.ReferencedCommand.Name}}
+		$cmdlets
+  		Write-Host "$($cmdlets.Length) alias cmdlets retrieved"
+	}
+	$aliasCmdlets = Start-ThreadJob -ScriptBlock $scriptBlock | Receive-Job -Wait
+
+ 	$aliasCmdletsCount = $aliasCmdlets.Length
+
+  	Write-Host "- Retrieving alias template page"
+	$aliasTemplatePageContent = Get-Content -Path "./dev/pages/cmdlets/alias.md" -Raw
+
+	ForEach($aliasCmdlet in $aliasCmdlets)
+	{
+		$destinationFileName = "./dev/documentation/$($aliasCmdlet.Alias).md"
+
+		Write-Host "- Creating page for $($aliasCmdlet.Alias) being an alias for $($aliasCmdlet.ReferencedCommand) as $destinationFileName" -ForegroundColor Yellow
+		$aliasTemplatePageContent.Replace("%%cmdletname%%", $aliasCmdlet.Alias).Replace("%%referencedcmdletname%%", $aliasCmdlet.ReferencedCommand) | Out-File $destinationFileName -Force
+	}
+}
+Catch {
+	Write-Host "Error: Cannot generate alias documentation files"
+	Write-Host $_
+}
+
+Write-Host "Copying documentation files to page cmdlets"
+
 Copy-Item -Path "./dev/documentation/*.md" -Destination "./dev/pages/cmdlets" -Force
 
 foreach ($nightlycmdlet in $nightlycmdlets) {
     if (!$releasedcmdlets.Contains($nightlycmdlet)) {
-        Copy-Item "./dev/documentation/$nightlycmdlet" -Destination "./dev/pages/cmdlets" -Force
+        Copy-Item "./dev/documentation/$nightlycmdlet" -Destination "./dev/pages/cmdlets" -Force | Out-Null
         # update the document to state it's only available in the nightly build
         $header = $fm.GetHeader("./dev/pages/cmdlets/$nightlycmdlet")
         $header["tags"] = "Available in the current Nightly Release only."
-        Write-Host "Writing $nightlycmdlet"
+        #Write-Host "Writing $nightlycmdlet"
         $fm.WriteHeader("./dev/pages/cmdlets/$nightlycmdlet",$header)
     }
 }
 
 # Generate cmdlet toc
+Write-Host "Retrieving all cmdlet pages"
 
 $cmdletPages = Get-ChildItem -Path "./dev/pages/cmdlets/*.md" -Exclude "index.md","alias.md"
 $toc = ""
@@ -88,13 +125,17 @@ $toc | Out-File "./dev/pages/cmdlets/toc.yml" -Force
 
 # Generate cmdlet index page
 
+Write-Host "Creating cmdlets index page"
+
 $cmdletIndexPageContent = Get-Content -Path "./dev/pages/cmdlets/index.md" -Raw
-$cmdletIndexPageContent = $cmdletIndexPageContent.Replace("%%cmdletcount%%", $cmdletPages.Length)
+$cmdletIndexPageContent = $cmdletIndexPageContent.Replace("%%cmdletcount%%", $cmdletPages.Length - $aliasCmdletsCount)
 
 $cmdletIndexPageList = ""
 $previousCmdletVerb = ""
 foreach ($cmdletPage in $cmdletPages)
 {
+    Write-Host "- $($cmdletPage.Name)"
+
     # Define the verb of the cmdlet
     if($cmdletPage.BaseName.Contains("-"))
     {
@@ -117,9 +158,17 @@ foreach ($cmdletPage in $cmdletPages)
     # Check if the cmdlet only exists in the nightly build
     if (!$releasedcmdlets.Contains($cmdletPage.Name))
     {
-        # Add an asterisk to the cmdlet name if it's only available in the nightly build
-        $cmdletIndexPageList = $cmdletIndexPageList + "*"
+        # Add a 1 to the cmdlet name if it's only available in the nightly build
+        $cmdletIndexPageList = $cmdletIndexPageList + " <sup>1</sup>"
     }
+
+    # Check if the cmdlet is an alias
+    if ($aliasCmdlets.Alias -contains $cmdletPage.BaseName)
+    {
+        # Add a 2 to the cmdlet name if it's an alias
+        $cmdletIndexPageList = $cmdletIndexPageList + " <sup>2</sup>"
+    }
+
     $cmdletIndexPageList = $cmdletIndexPageList + "`n"
 
     if($cmdletVerb -ne "")

pages/cmdlets/alias.md

@@ -10,8 +10,8 @@ online version: https://pnp.github.io/powershell/cmdlets/%%cmdletname%%.html
 # %%cmdletname%%
 
 ## SYNOPSIS
-This is an alias for [%%referencedcmdletname%%](./%%referencedcmdletname%%.md)
+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.
 
 ## RELATED LINKS
 
-[Microsoft 365 Patterns and Practices](https://aka.ms/m365pnp)
+[Microsoft 365 Patterns and Practices](https://aka.ms/m365pnp)

pages/cmdlets/index.md

@@ -1,5 +1,8 @@
 # PnP PowerShell cmdlets
 
-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.
+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. 
+
+<sup>1</sup>: Only available in the latest nightly build. All the others can also be used using the latest stable release.  
+<sup>2</sup>: Cmdlet is an alias of another cmdlet, used to provide backwards compatibility.
 
 %%cmdletlisting%%