(MAINT) Separately generate and test documentation

.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

grammars/tree-sitter-dscexpression/Cargo.toml

@@ -18,6 +18,7 @@ include = [
 
 [lib]
 path = "bindings/rust/lib.rs"
+doctest = false
 
 [dependencies]
 tree-sitter-rust = { workspace = true }

lib/dsc-lib-jsonschema/src/vscode/vscode_schema_extensions.rs

@@ -0,0 +1,32 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+//! Provides helper functions for working with VS Code's extended JSON Schema keywords with
+//! [`schemars::Schema`] instances.
+//!
+//! The `get_keyword_as_*` functions simplify retrieving the value of a keyword for a given type.
+//! If the schema defines the keyword with the expected type, those functions return a reference to
+//! that value as the correct type. If the keyword doesn't exist or has the wrong value type, the
+//! functions return [`None`].
+//!
+//! The rest of the utility methods work with specific keywords, like `$id` and `$defs`.
+
+use core::{clone::Clone, iter::Iterator, option::Option::None};
+use std::string::String;
+
+use schemars::Schema;
+use serde_json::{Map, Number, Value};
+use url::{Position, Url};
+
+type Array = Vec<Value>;
+type Object = Map<String, Value>;
+
+pub trait VSCodeSchemaExtensions {
+    fn has_markdown_description(&self) -> bool;
+}
+
+impl VSCodeSchemaExtensions for Schema {
+    fn has_markdown_description(&self) -> bool {
+        self.get("markdownDescription").is_some()
+    }
+}

lib/dsc-lib-osinfo/Cargo.toml

@@ -3,6 +3,9 @@ name = "dsc-lib-osinfo"
 version = "1.0.0"
 edition = "2021"
 
+[lib]
+doctest = false
+
 [dependencies]
 os_info = { workspace = true }
 serde = { workspace = true }

lib/dsc-lib-pal/Cargo.toml

@@ -5,5 +5,8 @@ name = "dsc-lib-pal"
 version = "0.1.0"
 edition = "2021"
 
+[lib]
+doctest = false
+
 [build-dependencies]
 cc = { workspace = true }

lib/dsc-lib-registry/Cargo.toml

@@ -8,6 +8,9 @@ available-locales = ["en-us"]
 default-locale = "en-us"
 load-path = "locales"
 
+[lib]
+doctest = false
+
 [dependencies]
 crossterm = { workspace = true }
 registry = { workspace = true }

lib/dsc-lib-security_context/Cargo.toml

@@ -3,6 +3,9 @@ name = "dsc-lib-security_context"
 version = "0.1.0"
 edition = "2021"
 
+[lib]
+doctest = false
+
 [target.'cfg(target_os = "windows")'.dependencies]
 is_elevated = { workspace = true }
 

lib/dsc-lib/Cargo.toml

@@ -3,6 +3,9 @@ name = "dsc-lib"
 version = "3.2.0"
 edition = "2021"
 
+[lib]
+doctest = false
+
 [dependencies]
 # external dependencies
 base32 = { workspace = true }