Publish exported function documentation to the wiki on merge

[Adam Rudell (arudell)]

Summary

Wires up the previously unused .build\generate-documentation.ps1 script and adds a new workflow that regenerates and publishes exported function documentation directly to the SdnDiagnostics.wiki repo on every merge to main that touches src/**. No generated documentation is stored in this source repo (.documentation/ remains gitignored, consistent with the change made in #52/aa47164).

This finishes the design already described in .github/contributing.md:

"The build pipeline leverages platyPS to auto-generate documentation for the exported functions and publishes to the project wiki."

The sync logic mirrors the actual structure of the SdnDiagnostics.wiki repo (hand-authored top-level pages, a functions\ subfolder for generated function docs, and _SideBar.md for navigation).

Changes

.build/generate-documentation.ps1

• Generates platyPS markdown docs for every exported function into .documentation/functions (gitignored, not committed to this repo).
• Added an optional -WikiPath parameter. When supplied, the script syncs generated docs into that wiki checkout:
  • Copies/overwrites function markdown pages into <wiki>\functions\ (matching the wiki's real folder layout — function pages are not stored at the wiki root).
  • Removes stale function pages from <wiki>\functions\ for functions that have since been removed/renamed, identified by matching PowerShell-approved-verb prefixes — hand-authored root pages (e.g. Home.md) are never touched.
  • Updates <wiki>\_SideBar.md (exact casing, matching the file already tracked in the wiki repo): only the ## Functions section is regenerated (alphabetical list of - [Name](Name) links); all hand-authored content above that heading (Documentation, How To Guides, Troubleshooting Guides, Learning sections, etc.) is preserved verbatim.

.github/workflows/publish-documentation.yml (new)

• Triggers on push to main (path-filtered to src/**) and workflow_dispatch.
• Checks out both the main repo and microsoft/SdnDiagnostics.wiki.
• Runs generate-documentation.ps1 -WikiPath <wiki checkout>.
• Commits and pushes only if there are actual content changes.

Testing

Ran generate-documentation.ps1 -WikiPath <temp dir> locally end-to-end against a seeded fake wiki checkout modeled on the real SdnDiagnostics.wiki structure (root Home.md, a functions\ subfolder, and a _SideBar.md with hand-authored sections above ## Functions plus one stale function entry):

• 122 function docs generated and synced into functions\.
• Home.md and all hand-authored _SideBar.md sections preserved untouched.
• Stale Get-OldStaleFunction.md removed from functions\ (no longer exported).
• ## Functions section of _SideBar.md regenerated correctly, alphabetically sorted.

Workflow YAML and script syntax validated (PowerShell AST parse + YAML parse).

Notes / follow-up

• The SdnDiagnostics.wiki repo already exists (confirmed, just hidden from repo navigation) with at least one commit, which actions/checkout requires.
• The workflow needs contents: write permission (scoped only to this job) to push to the wiki.
• The regenerated ## Functions list is sorted alphabetically for determinism/maintainability. This does not exactly match the current historical ordering in the wiki (which appears to reflect non-deterministic Get-Command module-load ordering across nested modules) — the first run of this workflow will reorder that section.

[Copilot]

Pull request overview

Adds automated generation and wiki publication of exported PowerShell function documentation.

Changes:

• Generates function pages and wiki navigation.
• Synchronizes generated pages through a new GitHub Actions workflow.
• Removes obsolete generated documentation.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File	Description
.build/generate-documentation.ps1	Generates, synchronizes, and removes function documentation.
.github/workflows/publish-documentation.yml	Publishes documentation to the project wiki.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.

Suppressed comments (3)

.github/workflows/publish-documentation.yml:19

• Concurrent pushes can start two publishers from the same wiki revision. Whichever pushes second will receive a non-fast-forward error; if that is the newer source revision, the wiki remains stale until another run. Serialize this workflow's publishing runs.

jobs:

.build/generate-documentation.ps1:60

• Get-Command -Module also returns exported aliases. This module exports Get-SdnEnvironmentInfo as an alias (src/SdnDiagnostics.psd1:181-184), while platyPS excludes aliases when generating module pages, so the sidebar will contain a dangling Get-SdnEnvironmentInfo link and stale-page detection will treat it as current. Restrict this list to functions.

$exportedFunctions = Get-Command -Module SdnDiagnostics | Sort-Object -Property Name

.github/workflows/publish-documentation.yml:22

• Manual dispatches can be run against any selectable branch, so this job can publish unmerged branch documentation to the production wiki while the commit message claims it came from main. Guard the publishing job so manual runs only operate on main.

  publish-documentation:
    # The type of runner that the job will run on
    runs-on: windows-latest

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.

Suppressed comments (2)

.build/generate-documentation.ps1:60

• The generated-file check only warns, but this same list is later used to build the manifest and sidebar. If platyPS omits a page, the workflow therefore succeeds and publishes a sidebar link for a file that was never copied. Treat any missing generated page as a fatal generation error so an incomplete wiki is not committed.

$exportedFunctions = Get-Command -Module SdnDiagnostics | Sort-Object -Property Name

.build/generate-documentation.ps1:158

• This workflow explicitly uses Windows PowerShell 5.1, where Set-Content defaults to the active ANSI code page rather than UTF-8. Rewriting _SideBar.md this way can corrupt non-ASCII text in the preserved hand-authored prefix. Read and write the sidebar with an explicit UTF-8 encoding (including the Get-Content call above).

        else {

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.

Suppressed comments (2)

.build/generate-documentation.ps1:64

• Missing generated pages are only logged, but the later manifest and sidebar still include every exported function. If platyPS skips a command, this workflow therefore publishes a broken link and records the nonexistent page as generated. Fail generation when this check finds any missing function instead of continuing.

$exportedFunctions = Get-Command -Module SdnDiagnostics | Sort-Object -Property Name
$currentFiles = Get-ChildItem -Path $docPath\* -Include *.md
foreach($function in $exportedFunctions){
    if($function.Name -inotin ($currentFiles).BaseName){
        "Documentation not generated for {0}" -f $function.Name | Write-Host -ForegroundColor:Yellow

.github/workflows/publish-documentation.yml:44

• actions/checkout defaults to the event ref, so a manual dispatch from a feature branch can publish unmerged source to the production wiki. It also leaves serialized push runs tied to their historical event SHAs rather than the current main tip. Explicitly check out main for this publishing job and derive the commit label from that checkout's HEAD.

      - name: 'Checkout SdnDiagnostics'
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          path: main