From 3a5a6d6514f2f84fbffb096ae83ccb32d4edf187 Mon Sep 17 00:00:00 2001 From: Thomas Nieto <38873752+ThomasNieto@users.noreply.github.com> Date: Mon, 28 Jul 2025 08:19:15 -0500 Subject: [PATCH 1/3] Fix _purge example (#360) --- .../dsc-3.0/reference/schemas/resource/properties/purge.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/properties/purge.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/properties/purge.md index 54d4feb..dc42743 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/properties/purge.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/properties/purge.md @@ -43,7 +43,7 @@ To add this property to a resource's instance schema, define the property with t snippet: ```json -"_inDesiredState": { +"_purge": { "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/resource/properties/purge.json" } ``` From 13fe3436c2982f615ab218b9a1b6bc2dc5f18556 Mon Sep 17 00:00:00 2001 From: "Mikey Lombardi (He/Him)" Date: Mon, 28 Jul 2025 15:34:51 -0500 Subject: [PATCH 2/3] (GH-359) Fix resource `kind` (#361) Prior to this change, the resource `kind` in the root manifest reference wasn't updated to reflect the correct casing or all valid options. This change ensures that the reference in the manifest root matches the subschema reference. --- .../reference/schemas/definitions/resourceKind.md | 2 +- .../reference/schemas/resource/manifest/root.md | 13 +++++++------ 2 files changed, 8 insertions(+), 7 deletions(-) diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/definitions/resourceKind.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/definitions/resourceKind.md index 6c54685..bcd429c 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/definitions/resourceKind.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/definitions/resourceKind.md @@ -22,7 +22,7 @@ ValidValues: [resource, adapter, group, importer, exporter] ## Description -DSC supports three kinds of command-based DSC Resources: +DSC supports several kinds of command-based DSC Resources: - `resource` - Indicates that the manifest isn't for a group or adapter resource. - `group` - Indicates that the manifest is for a [group resource](#group-resources). diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/root.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/root.md index 502aebb..1c7628d 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/root.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/root.md @@ -165,23 +165,24 @@ Required: false ### kind -The `kind` property defines how DSC should handle the resource. DSC supports three kinds of -command-based DSC Resources: `Resource`, `Group`, and `Adapter`. +The `kind` property defines how DSC should handle the resource. DSC supports several kinds +ofcommand-based DSC Resources: `resource`, `group`, `adapter`, `importer`, and `exporter`. When `kind` isn't defined in the resource manifest, DSC infers the value for the property. If the `adapter` property is defined in the resource manifest, DSC infers the value of `kind` as -`Adapter`. If the `adapter` property isn't defined, DSC infers the value of `kind` as `Resource`. -DSC can't infer whether a manifest is for a group resource. +`adapter`. If the `adapter` property isn't defined, DSC infers the value of `kind` as `resource`. +DSC can't infer whether a manifest is for a group` or importer resource. When defining a group resource, always explicitly define the `kind` property in the manifest as -`Group`. +`group`. When defining an importer resource, always explicitly define the `kind` property in the +manifest as `importer`. For more information, see [DSC Resource kind schema reference][02]. ```yaml Type: string Required: false -ValidValues: [Resource, Adapter, Group] +ValidValues: [resource, adapter, group, importer, exporter] ``` ### tags From 467847f8de8f0660cd69d0ba081a494cf5aa7bb0 Mon Sep 17 00:00:00 2001 From: "Mikey Lombardi (He/Him)" Date: Mon, 28 Jul 2025 15:35:32 -0500 Subject: [PATCH 3/3] (MAINT) Decompose TOC (#362) * (MAINT) Decompose TOC Prior to this change, the TOC for the documentation was contained in a single top-level configuration file, which was difficult to parse, reason about, and maintain. This change decomposes the TOC into smaller files colocated with the documentation for a smaller scope of management, easier maintanence, and readability. * (MAINT) Add missing TOC entries. --- dsc/docs-conceptual/dsc-3.0/concepts/toc.yml | 25 ++ .../dsc-3.0/reference/cli/toc.yml | 43 +++ .../dsc-3.0/reference/resources/toc.yml | 75 ++++++ .../dsc-3.0/reference/schemas/toc.yml | 151 +++++++++++ dsc/docs-conceptual/dsc-3.0/reference/toc.yml | 9 + .../dsc-3.0/reference/tools/toc.yaml | 31 +++ dsc/docs-conceptual/dsc-3.0/toc.yml | 253 +----------------- 7 files changed, 337 insertions(+), 250 deletions(-) create mode 100644 dsc/docs-conceptual/dsc-3.0/concepts/toc.yml create mode 100644 dsc/docs-conceptual/dsc-3.0/reference/cli/toc.yml create mode 100644 dsc/docs-conceptual/dsc-3.0/reference/resources/toc.yml create mode 100644 dsc/docs-conceptual/dsc-3.0/reference/schemas/toc.yml create mode 100644 dsc/docs-conceptual/dsc-3.0/reference/toc.yml create mode 100644 dsc/docs-conceptual/dsc-3.0/reference/tools/toc.yaml diff --git a/dsc/docs-conceptual/dsc-3.0/concepts/toc.yml b/dsc/docs-conceptual/dsc-3.0/concepts/toc.yml new file mode 100644 index 0000000..971e50e --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/concepts/toc.yml @@ -0,0 +1,25 @@ +items: + - name: DSC configuration documents + items: + - name: Overview + href: configuration-documents/overview.md + - name: DSC resources + items: + - name: Overview + href: resources/overview.md + - name: Resource instances + href: resources/instances.md + - name: Resource operations + href: resources/operations.md + - name: Resource properties + href: resources/properties.md + - name: Resource capabilities + href: resources/capabilities.md + - name: Resource kinds + href: resources/kinds.md + - name: Anatomy of a command resource + href: resources/anatomy.md + - name: Enhanced authoring + href: enhanced-authoring.md + - name: Output accessibility + href: output-accessibility.md \ No newline at end of file diff --git a/dsc/docs-conceptual/dsc-3.0/reference/cli/toc.yml b/dsc/docs-conceptual/dsc-3.0/reference/cli/toc.yml new file mode 100644 index 0000000..9bf1fb9 --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/cli/toc.yml @@ -0,0 +1,43 @@ +items: + - name: dsc + href: index.md + - name: dsc completer + href: completer/index.md + - name: dsc config subcommands + items: + - name: dsc config + href: config/index.md + - name: dsc config export + href: config/export.md + - name: dsc config get + href: config/get.md + - name: dsc config set + href: config/set.md + - name: dsc config test + href: config/test.md + - name: dsc extension subcommands + items: + - name: dsc extension + href: extension/index.md + - name: dsc extension list + href: extension/list.md + - name: dsc resource subcommands + items: + - name: dsc resource + href: resource/index.md + - name: dsc resource delete + href: resource/delete.md + - name: dsc resource export + href: resource/export.md + - name: dsc resource get + href: resource/get.md + - name: dsc resource list + href: resource/list.md + - name: dsc resource schema + href: resource/schema.md + - name: dsc resource set + href: resource/set.md + - name: dsc resource test + href: resource/test.md + - name: dsc schema + href: schema/index.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/resources/toc.yml b/dsc/docs-conceptual/dsc-3.0/reference/resources/toc.yml new file mode 100644 index 0000000..d279b0d --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/resources/toc.yml @@ -0,0 +1,75 @@ +items: + - name: Builtin resources + items: + - name: Overview + href: builtin.md + - name: DSC.PackageManagement/APT + items: + - name: DSC resource + href: DSC/PackageManagement/APT/index.md + - name: Examples + items: + - name: Manage packages + href: DSC/PackageManagement/APT/examples/manage-packages-with-apt.md + - name: Microsoft.DSC.Debug/Echo + items: + - name: DSC resource + href: Microsoft/DSC/Debug/Echo/index.md + - name: Examples + items: + - name: Basic usage + href: Microsoft/DSC/Debug/Echo/examples/basic-echo-example.md + - name: Microsoft.DSC/PowerShell + items: + - name: DSC resource + href: Microsoft/Dsc/PowerShell/index.md + - name: Microsoft/OSInfo + items: + - name: DSC resource + href: Microsoft/OSInfo/index.md + - name: Examples + items: + - name: Validate OS with dsc resource commands + href: Microsoft/OSInfo/examples/validate-with-dsc-resource.md + - name: Validate OS in a configuration + href: Microsoft/OSInfo/examples/validate-with-dsc-resource.md + - name: Microsoft.Windows/RebootPending + items: + - name: DSC resource + href: Microsoft/Windows/RebootPending/index.md + - name: Examples + items: + - name: Check for pending reboot + href: Microsoft/Windows/RebootPending/examples/check-for-pending-reboot.md + - name: Use in configuration + href: Microsoft/Windows/RebootPending/examples/use-rebootpending-in-configuration.md + - name: Microsoft.Windows/Registry + items: + - name: DSC resource + href: Microsoft/Windows/Registry/index.md + - name: Examples + items: + - name: Manage a key + href: Microsoft/Windows/Registry/examples/manage-a-registry-key.md + - name: Manage a value + href: Microsoft/Windows/Registry/examples/manage-a-registry-value.md + - name: Configure keys and values + href: Microsoft/Windows/Registry/examples/configure-registry-keys-and-values.md + - name: Microsoft.Windows/WindowsPowerShell + items: + - name: DSC resource + href: Microsoft/Windows/WindowsPowerShell/index.md + - name: Examples + items: + - name: Manage a Windows service + href: Microsoft/Windows/WindowsPowerShell/examples/manage-a-windows-service.md + - name: Microsoft.Windows/WMI + items: + - name: DSC resource + href: Microsoft/Windows/WMI/index.md + - name: Examples + items: + - name: Query operating system + href: Microsoft/Windows/WMI/examples/query-operating-system-info.md + - name: Query filtered disk + href: Microsoft/Windows/WMI/examples/query-filtered-disk-info.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/toc.yml b/dsc/docs-conceptual/dsc-3.0/reference/schemas/toc.yml new file mode 100644 index 0000000..de60218 --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/toc.yml @@ -0,0 +1,151 @@ +items: + - name: Overview + href: overview.md + - name: Schema URIs + href: schema-uris.md + - name: dsc command outputs + items: + - name: dsc config command outputs + items: + - name: dsc config get output + href: outputs/config/get.md + - name: dsc config set output + href: outputs/config/set.md + - name: dsc config test output + href: outputs/config/test.md + - name: dsc extension command outputs + items: + - name: dsc extension list output + href: outputs/extension/list.md + - name: dsc resource command outputs + items: + - name: dsc resource get output + href: outputs/resource/get.md + - name: dsc resource list output + href: outputs/resource/list.md + - name: dsc resource set output + href: outputs/resource/set.md + - name: dsc resource test output + href: outputs/resource/test.md + - name: Configuration + items: + - name: Documents + href: config/document.md + - name: Document metadata + href: config/metadata.md + - name: Document parameters + href: config/parameter.md + - name: Resource instances + href: config/resource.md + - name: Functions + items: + - name: Overview + href: config/functions/overview.md + - name: add + href: config/functions/add.md + - name: base64 + href: config/functions/base64.md + - name: concat + href: config/functions/concat.md + - name: createArray + href: config/functions/createArray.md + - name: div + href: config/functions/div.md + - name: envvar + href: config/functions/envvar.md + - name: equals + href: config/functions/equals.md + - name: format + href: config/functions/format.md + - name: if + href: config/functions/if.md + - name: int + href: config/functions/int.md + - name: max + href: config/functions/max.md + - name: min + href: config/functions/min.md + - name: mod + href: config/functions/mod.md + - name: mul + href: config/functions/mul.md + - name: parameters + href: config/functions/parameters.md + - name: reference + href: config/functions/reference.md + - name: resourceId + href: config/functions/resourceId.md + - name: sub + href: config/functions/sub.md + - name: variables + href: config/functions/variables.md + - name: Extension + items: + - name: Manifests + items: + - name: Root + href: extension/manifest/root.md + - name: Discover property + href: extension/manifest/discover.md + - name: Expected stdout + items: + - name: Discover operation stdout + href: extension/stdout/discover.md + - name: Resource + items: + - name: Manifests + items: + - name: Root + href: resource/manifest/root.md + - name: adapter command field + href: resource/manifest/adapter.md + - name: delete command field + href: resource/manifest/delete.md + - name: export command field + href: resource/manifest/export.md + - name: get command field + href: resource/manifest/get.md + - name: set command field + href: resource/manifest/set.md + - name: whatIf command field + href: resource/manifest/whatIf.md + - name: test command field + href: resource/manifest/test.md + - name: validate command field + href: resource/manifest/validate.md + - name: resolve command field + href: resource/manifest/resolve.md + - name: schema field + items: + - name: Command + href: resource/manifest/schema/property.md + - name: Embedded schemas + href: resource/manifest/schema/embedded.md + - name: Canonical resource properties + items: + - name: Overview + href: resource/properties/overview.md + - name: _ensure + href: resource/properties/ensure.md + - name: _exist + href: resource/properties/exist.md + - name: _inDesiredState + href: resource/properties/inDesiredState.md + - name: _purge + href: resource/properties/purge.md + - name: _rebootRequested + href: resource/properties/rebootRequested.md + - name: Metadata + items: + - name: Microsoft.DSC properties + href: metadata/Microsoft.DSC/properties.md + - name: Shared definitions + items: + - name: message + href: definitions/message.md + - name: resourceKind + href: definitions/resourceKind.md + - name: resourceType + href: definitions/resourceType.md + - name: Parameter dataTypes + href: definitions/parameters/dataTypes.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/toc.yml b/dsc/docs-conceptual/dsc-3.0/reference/toc.yml new file mode 100644 index 0000000..7e3f7e4 --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/toc.yml @@ -0,0 +1,9 @@ +items: + - name: DSC CLI + href: cli/toc.yml + - name: DSC JSON Schemas + href: schemas/toc.yml + - name: DSC resources + href: resources/toc.yml + - name: DSC tools + href: tools/toc.yml \ No newline at end of file diff --git a/dsc/docs-conceptual/dsc-3.0/reference/tools/toc.yaml b/dsc/docs-conceptual/dsc-3.0/reference/tools/toc.yaml new file mode 100644 index 0000000..14725d1 --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/tools/toc.yaml @@ -0,0 +1,31 @@ +items: + - name: Builtin commands + items: + - name: Overview + href: builtin.md + - name: osinfo + href: osinfo.md + - name: registry commandline + items: + - name: registry + href: registry/index.md + - name: registry query + href: registry/query/index.md + - name: registry set + href: registry/set/index.md + - name: registry remove + href: registry/remove/index.md + - name: registry find + href: registry/find/index.md + - name: registry config subcommands + items: + - name: registry config + href: registry/config/index.md + - name: registry config get + href: registry/config/get.md + - name: registry config set + href: registry/config/set.md + - name: registry config delete + href: registry/config/delete.md + - name: registry schema + href: registry/schema/index.md diff --git a/dsc/docs-conceptual/dsc-3.0/toc.yml b/dsc/docs-conceptual/dsc-3.0/toc.yml index 32e9851..3d6b1c1 100644 --- a/dsc/docs-conceptual/dsc-3.0/toc.yml +++ b/dsc/docs-conceptual/dsc-3.0/toc.yml @@ -8,31 +8,7 @@ items: - name: Managing state with DSC href: get-started/index.md - name: Concepts - items: - - name: DSC configuration documents - items: - - name: Overview - href: concepts/configuration-documents/overview.md - - name: DSC resources - items: - - name: Overview - href: concepts/resources/overview.md - - name: Resource instances - href: concepts/resources/instances.md - - name: Resource operations - href: concepts/resources/operations.md - - name: Resource properties - href: concepts/resources/properties.md - - name: Resource capabilities - href: concepts/resources/capabilities.md - - name: Resource kinds - href: concepts/resources/kinds.md - - name: Anatomy of a command resource - href: concepts/resources/anatomy.md - - name: Enhanced authoring - href: concepts/enhanced-authoring.md - - name: Output accessibility - href: concepts/output-accessibility.md + href: concepts/toc.yml - name: Tutorials items: - name: Resource authoring @@ -46,229 +22,6 @@ items: - name: In Go href: https://powershell.github.io/DSC-Samples/tutorials/first-resource/go/ - name: DSC reference - items: - - name: DSC CLI - items: - - name: dsc - href: reference/cli/index.md - - name: dsc completer - href: reference/cli/completer/index.md - - name: dsc config subcommands - items: - - name: dsc config - href: reference/cli/config/index.md - - name: dsc config export - href: reference/cli/config/export.md - - name: dsc config get - href: reference/cli/config/get.md - - name: dsc config set - href: reference/cli/config/set.md - - name: dsc config test - href: reference/cli/config/test.md - - name: dsc resource subcommands - items: - - name: dsc resource - href: reference/cli/resource/index.md - - name: dsc resource delete - href: reference/cli/resource/delete.md - - name: dsc resource export - href: reference/cli/resource/export.md - - name: dsc resource get - href: reference/cli/resource/get.md - - name: dsc resource list - href: reference/cli/resource/list.md - - name: dsc resource schema - href: reference/cli/resource/schema.md - - name: dsc resource set - href: reference/cli/resource/set.md - - name: dsc resource test - href: reference/cli/resource/test.md - - name: dsc schema - href: reference/cli/schema/index.md - - name: DSC JSON Schemas - items: - - name: Overview - href: reference/schemas/overview.md - - name: Schema URIs - href: reference/schemas/schema-uris.md - - name: dsc command outputs - items: - - name: dsc config command outputs - items: - - name: dsc config get output - href: reference/schemas/outputs/config/get.md - - name: dsc config set output - href: reference/schemas/outputs/config/set.md - - name: dsc config test output - href: reference/schemas/outputs/config/test.md - - name: dsc resource command outputs - items: - - name: dsc resource get output - href: reference/schemas/outputs/resource/get.md - - name: dsc resource list output - href: reference/schemas/outputs/resource/list.md - - name: dsc resource set output - href: reference/schemas/outputs/resource/set.md - - name: dsc resource test output - href: reference/schemas/outputs/resource/test.md - - name: Configuration - items: - - name: Documents - href: reference/schemas/config/document.md - - name: Document metadata - href: reference/schemas/config/metadata.md - - name: Document parameters - href: reference/schemas/config/parameter.md - - name: Resource instances - href: reference/schemas/config/resource.md - - name: Functions - items: - - name: Overview - href: reference/schemas/config/functions/overview.md - - name: add - href: reference/schemas/config/functions/add.md - - name: base64 - href: reference/schemas/config/functions/base64.md - - name: concat - href: reference/schemas/config/functions/concat.md - - name: createArray - href: reference/schemas/config/functions/createArray.md - - name: div - href: reference/schemas/config/functions/div.md - - name: envvar - href: reference/schemas/config/functions/envvar.md - - name: int - href: reference/schemas/config/functions/int.md - - name: max - href: reference/schemas/config/functions/max.md - - name: min - href: reference/schemas/config/functions/min.md - - name: mod - href: reference/schemas/config/functions/mod.md - - name: mul - href: reference/schemas/config/functions/mul.md - - name: parameters - href: reference/schemas/config/functions/parameters.md - - name: reference - href: reference/schemas/config/functions/reference.md - - name: resourceId - href: reference/schemas/config/functions/resourceId.md - - name: sub - href: reference/schemas/config/functions/sub.md - - name: Resource - items: - - name: Manifests - items: - - name: Root - href: reference/schemas/resource/manifest/root.md - - name: Adapter property - href: reference/schemas/resource/manifest/adapter.md - - name: Delete property - href: reference/schemas/resource/manifest/delete.md - - name: Export property - href: reference/schemas/resource/manifest/export.md - - name: Get property - href: reference/schemas/resource/manifest/get.md - - name: Set property - href: reference/schemas/resource/manifest/set.md - - name: Test property - href: reference/schemas/resource/manifest/test.md - - name: Validate property - href: reference/schemas/resource/manifest/validate.md - - name: Schema - items: - - name: Property - href: reference/schemas/resource/manifest/schema/property.md - - name: Embedded schemas - href: reference/schemas/resource/manifest/schema/embedded.md - - name: Canonical resource properties - items: - - name: Overview - href: reference/schemas/resource/properties/overview.md - - name: _ensure - href: reference/schemas/resource/properties/ensure.md - - name: _exist - href: reference/schemas/resource/properties/exist.md - - name: _inDesiredState - href: reference/schemas/resource/properties/inDesiredState.md - - name: _purge - href: reference/schemas/resource/properties/purge.md - - name: _rebootRequested - href: reference/schemas/resource/properties/rebootRequested.md - - name: Metadata - items: - - name: Microsoft.DSC properties - href: reference/schemas/metadata/Microsoft.DSC/properties.md - - name: Shared definitions - items: - - name: message - href: reference/schemas/definitions/message.md - - name: resourceKind - href: reference/schemas/definitions/resourceKind.md - - name: resourceType - href: reference/schemas/definitions/resourceType.md - - name: Parameter dataTypes - href: reference/schemas/definitions/parameters/dataTypes.md - - - name: DSC resources - items: - - name: Builtin resources - items: - - name: Overview - href: reference/resources/builtin.md - - name: Microsoft/OSInfo - items: - - name: DSC Resource - href: reference/resources/Microsoft/OSInfo/index.md - - name: Examples - items: - - name: Validate OS with dsc resource commands - href: reference/resources/Microsoft/OSInfo/examples/validate-with-dsc-resource.md - - name: Validate OS in a configuration - href: reference/resources/Microsoft/OSInfo/examples/validate-with-dsc-resource.md - - name: Microsoft.Windows/Registry - items: - - name: DSC Resource - href: reference/resources/Microsoft/Windows/Registry/index.md - - name: Examples - items: - - name: Manage a key - href: reference/resources/Microsoft/Windows/Registry/examples/manage-a-registry-key.md - - name: Manage a value - href: reference/resources/Microsoft/Windows/Registry/examples/manage-a-registry-value.md - - name: Configure keys and values - href: reference/resources/Microsoft/Windows/Registry/examples/configure-registry-keys-and-values.md - - name: DSC tools - items: - - name: Builtin commands - items: - - name: Overview - href: reference/tools/builtin.md - - name: osinfo - href: reference/tools/osinfo.md - - name: registry commandline - items: - - name: registry - href: reference/tools/registry/index.md - - name: registry query - href: reference/tools/registry/query/index.md - - name: registry set - href: reference/tools/registry/set/index.md - - name: registry remove - href: reference/tools/registry/remove/index.md - - name: registry find - href: reference/tools/registry/find/index.md - - name: registry config subcommands - items: - - name: registry config - href: reference/tools/registry/config/index.md - - name: registry config get - href: reference/tools/registry/config/get.md - - name: registry config set - href: reference/tools/registry/config/set.md - - name: registry config delete - href: reference/tools/registry/config/delete.md - - name: registry schema - href: reference/tools/registry/schema/index.md + href: reference/toc.yml - name: Glossary - href: glossary.md \ No newline at end of file + href: glossary.md