(MAINT) Enable generating/testing docs in CI

This change updates the build helpers module to enable separately
generating documentation for Rust crates and testing the examples in
that documentation.

It also adds a new workflow job for generating and testing documentation
separately from the rest of the build and test scripts. While these jobs
failing won't prevent the continued unit/integration/acceptance tests,
it will still fail the build.

This should help ensure that any examples in our documentation remain
valid. It _doesn't_ test to ensure that public APIs are documented, only
that the documentation that exists is minimally valid.

Author: michaeltlombardi

.github/workflows/rust.yml

@@ -19,6 +19,28 @@ defaults:
     shell: pwsh
 
 jobs:
+  docs:
+    strategy:
+      matrix:
+        platform: [ubuntu-latest, macos-latest, windows-latest]
+    runs-on: ${{matrix.platform}}
+    steps:
+      - uses: actions/checkout@v5
+      - name: Install prerequisites
+        run: ./build.new.ps1 -SkipBuild -Clippy -Verbose
+      - name: Generate documentation
+        run: ./build.new.ps1 -RustDocs -Verbose
+      - name: Test documentation
+        run: |-
+          $testParams = @{
+            SkipBuild          = $true
+            RustDocs           = $true
+            Test               = $true
+            ExcludeRustTests   = $true
+            ExcludePesterTests = $true
+            Verbose            = $true
+          }
+          ./build.new.ps1 @testParams
   linux-build:
     runs-on: ubuntu-latest
     steps:

build.helpers.psm1

@@ -1229,14 +1229,62 @@ function Copy-BuildArtifact {
 }
 #endregion Build project functions
 
+#region    Documenting project functions
+function Export-RustDocs {
+    [CmdletBinding()]
+    param(
+        [DscProjectDefinition[]]$Project,
+        [ValidateSet('current','aarch64-pc-windows-msvc','x86_64-pc-windows-msvc','aarch64-apple-darwin','x86_64-apple-darwin','aarch64-unknown-linux-gnu','aarch64-unknown-linux-musl','x86_64-unknown-linux-gnu','x86_64-unknown-linux-musl')]
+        $Architecture = 'current',
+        [switch]$Release,
+        [switch]$IncludeDependencies
+    )
+
+    begin {
+        $flags = @($Release ? '-r' : $null)
+        if ($Architecture -ne 'current') {
+            $flags += '--target'
+            $flags += $Architecture
+        } else {
+            $memberGroup = if ($IsLinux) {
+                'Linux'
+            } elseif ($IsMacOS) {
+                'macOS'
+            } elseif ($IsWindows) {
+                'Windows'
+            }
+            Set-DefaultWorkspaceMemberGroup -MemberGroup $memberGroup
+        }
+        if (-not $IncludeDependencies) {
+            $flags += '--no-deps'
+        }
+    }
+
+    process {
+        $members = Get-DefaultWorkspaceMemberGroup
+        Write-Verbose -Verbose "Exporting documentation for rust projects: [$members]"
+        cargo doc @flags
+
+        if ($null -ne $LASTEXITCODE -and $LASTEXITCODE -ne 0) {
+            Write-Error "Last exit code is $LASTEXITCODE, 'cargo doc' failed"
+        }
+    }
+
+    clean {
+        Reset-DefaultWorkspaceMemberGroup
+    }
+}
+#endregion Documenting project functions
+
 #region    Test project functions
 function Test-RustProject {
     [CmdletBinding()]
     param(
         [DscProjectDefinition[]]$Project,
         [ValidateSet('current','aarch64-pc-windows-msvc','x86_64-pc-windows-msvc','aarch64-apple-darwin','x86_64-apple-darwin','aarch64-unknown-linux-gnu','aarch64-unknown-linux-musl','x86_64-unknown-linux-gnu','x86_64-unknown-linux-musl')]
         $Architecture = 'current',
-        [switch]$Release
+        [switch]$Release,
+        [switch]$Docs
     )
 
     begin {
@@ -1254,11 +1302,18 @@ function Test-RustProject {
             }
             Set-DefaultWorkspaceMemberGroup -MemberGroup $memberGroup
         }
+        if ($Docs) {
+            $flags += '--doc'
+        }
     }
 
     process {
         $members = Get-DefaultWorkspaceMemberGroup
-        Write-Verbose -Verbose "Testing rust projects: [$members]"
+        if ($Docs) {
+            Write-Verbose -Verbose "Testing documentation for rust projects: [$members]"
+        } else {
+            Write-Verbose -Verbose "Testing rust projects: [$members]"
+        }
         cargo test @flags
 
         if ($null -ne $LASTEXITCODE -and $LASTEXITCODE -ne 0) {

build.new.ps1

@@ -97,6 +97,7 @@ param(
     [switch]$UseCFSAuth,
     [switch]$Clean,
     [switch]$CacheRustBuild,
+    [switch]$RustDocs,
     [switch]$Quiet
 )
 
@@ -221,18 +222,31 @@ process {
     if (!$SkipBuild) {
         $progressParams.Activity = 'Building the projects'
         Write-BuildProgress @progressParams
-        $buildParams = @{
-            Project      = $BuildData.Projects
-            Architecture = $Architecture
-            Release      = $Release
-            Clean        = $Clean
-        }
         Write-BuildProgress @progressParams -Status 'Generating grammar bindings'
         Export-GrammarBinding -Project $BuildData.Projects @VerboseParam
-        Write-BuildProgress @progressParams -Status 'Compiling Rust'
-        Build-RustProject @buildParams -Audit:$Audit -Clippy:$Clippy @VerboseParam
-        Write-BuildProgress @progressParams -Status "Copying build artifacts"
-        Copy-BuildArtifact @buildParams -ExecutableFile $BuildData.PackageFiles.Executable @VerboseParam
+
+        if ($RustDocs) {
+            $progressParams.Activity = 'Generating Rust documentation'
+            Write-BuildProgress @progressParams
+
+            $docsParams = @{
+                Project      = $BuildData.Projects
+                Architecture = $Architecture
+                Release      = $Release
+            }
+            Export-RustDocs @docsParams @VerboseParam
+        } else {
+            $buildParams = @{
+                Project      = $BuildData.Projects
+                Architecture = $Architecture
+                Release      = $Release
+                Clean        = $Clean
+            }
+            Write-BuildProgress @progressParams -Status 'Compiling Rust'
+            Build-RustProject @buildParams -Audit:$Audit -Clippy:$Clippy @VerboseParam
+            Write-BuildProgress @progressParams -Status "Copying build artifacts"
+            Copy-BuildArtifact @buildParams -ExecutableFile $BuildData.PackageFiles.Executable @VerboseParam
+        }
     }
 
     # Ensure PATH includes the output artifacts after building and before testing.
@@ -255,6 +269,16 @@ process {
             Write-BuildProgress @progressParams -Status "Testing Rust projects"
             Test-RustProject @rustTestParams @VerboseParam
         }
+        if ($RustDocs) {
+            $docTestParams = @{
+                Project      = $BuildData.Projects
+                Architecture = $Architecture
+                Release      = $Release
+                Docs         = $true
+            }
+            Write-BuildProgress @progressParams -Status "Testing documentation for Rust projects"
+            Test-RustProject @docTestParams @VerboseParam
+        }
         if (-not $ExcludePesterTests) {
             $installParams = @{
                 UsingADO = $usingADO