(AB#118304) Add reference docs for command-based resources #181
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This comment was marked as outdated.
This comment was marked as outdated.
04bed6c to
4e107f2
Compare
This comment was marked as outdated.
This comment was marked as outdated.
4e107f2 to
a5c06f8
Compare
This comment was marked as outdated.
This comment was marked as outdated.
a5c06f8 to
c85d1ab
Compare
This comment was marked as outdated.
This comment was marked as outdated.
c85d1ab to
eb8fbef
Compare
This comment was marked as outdated.
This comment was marked as outdated.
eb8fbef to
73fa72c
Compare
This comment was marked as outdated.
This comment was marked as outdated.
This change adds reference documentation for the proof-of-concept prototype command-based DSC Resources `Microsoft/OSInfo` and `Microsoft.Windows/Registry`. The reference documentation proposes a structure for the reference documentation for command-based resources based on the reference documentation used for the PSDscResources in v2. It also documents the command-line tools the resources use. While these commands and resources are not production-ready, they are the only command-based resources we can reference in the documentation at this time. If the resources are removed or replaced in the future, the documentation can be updated. This change: - Fixes AB#118304 - Fixes AB#118305 - Fixes AB#118306
73fa72c to
74de31a
Compare
sdwheeler
approved these changes
Aug 24, 2023
michaeltlombardi
added a commit
to michaeltlombardi/DSC
that referenced
this pull request
Aug 24, 2023
This change updates the `Microsoft/OSInfo` resource based on the work for documenting it in MicrosoftDocs/PowerShell-Docs-DSC#181 This change: - Minimally modifies the README for grammar and formatting. - Adds docs strings to the types in the source code. - Adds a canonical schema for the resource, and a YAML version of the schema for easier reading and maintaining. - Updates the resource manifest to embed the canonical schema and to add the `url` property to point to the canonical schema. The canonical schema is generated from the YAML version using the following command: ```powershell $YamlPath = Resolve-Path -Path .\schemas\resources\Microsoft\OSInfo\v0.1.0\schema.yaml | Select-Object -ExpandProperty Path $JsonPath = $YamlPath -replace '\.yaml$', '.json' $Schema = Get-Content -Raw -Path $YamlPath | ConvertFrom-Yaml $Schema.'$id' = $Schema.'$id' -replace '\.yaml$', '.json' $Schema | ConvertTo-Json -Depth 100 | Out-File -Encoding utf8 -Path $JsonPath -Force ``` The schema uses the first sentence from the documentation as the value for the `description` keyword for each property, replacing backticks with single quotes, as the `description` keyword doesn't reliably render as Markdown for editors that support hover help for JSON schemas. After every description string is the link to that property in the documentation. The `markdownDescription` is a non-standard keyword supported by the JSON and YAML language servers in VS Code. When it is a non-empty string for a schema or subschema, it's rendered and used in the hover text instead of the `description` keyword. The other major change in the schema is to replace the semantically incorrect multi-type of `null` and `string` with a single type of `string`. The [JSON schema documentation][01] states: > It's important to remember that in JSON, null isn't equivalent to > something being absent. For JSON schemas, the `required` keyword indicates whether a property is required. By convention, if a property isn't required and isn't intended to be semantically `null`, it should be omitted from the JSON representation of the object instance. Using `null` in a multi-type should be reserved for when a `null` value carries specific semantics. [01]: https://json-schema.org/understanding-json-schema/reference/null.html#null
michaeltlombardi
added a commit
to michaeltlombardi/DSC
that referenced
this pull request
Aug 24, 2023
This change updates the `Microsoft/OSInfo` resource based on the work for documenting it in MicrosoftDocs/PowerShell-Docs-DSC#181 This change: - Minimally modifies the README for grammar and formatting. - Adds docs strings to the types in the source code. - Adds a canonical schema for the resource, and a YAML version of the schema for easier reading and maintaining. - Updates the resource manifest to embed the canonical schema. The canonical schema is generated from the YAML version using the following command: ```powershell $YamlPath = Resolve-Path -Path .\schemas\resources\Microsoft\OSInfo\v0.1.0\schema.yaml | Select-Object -ExpandProperty Path $JsonPath = $YamlPath -replace '\.yaml$', '.json' $Schema = Get-Content -Raw -Path $YamlPath | ConvertFrom-Yaml $Schema.'$id' = $Schema.'$id' -replace '\.yaml$', '.json' $Schema | ConvertTo-Json -Depth 100 | Out-File -Encoding utf8 -Path $JsonPath -Force ``` The schema uses the first sentence from the documentation as the value for the `description` keyword for each property, replacing backticks with single quotes, as the `description` keyword doesn't reliably render as Markdown for editors that support hover help for JSON schemas. After every description string is the link to that property in the documentation. The `markdownDescription` is a non-standard keyword supported by the JSON and YAML language servers in VS Code. When it's a non-empty string for a schema or subschema, it's rendered and used in the hover text instead of the `description` keyword. The other major change in the schema is to replace the semantically incorrect multi-type of `null` and `string` with a single type of `string`. The [JSON schema documentation][01] states: > It's important to remember that in JSON, null isn't equivalent to > something being absent. For JSON schemas, the `required` keyword indicates whether a property is required. By convention, if a property isn't required and isn't intended to be semantically `null`, it should be omitted from the JSON representation of the object instance. Using `null` in a multi-type should be reserved for when a `null` value carries specific semantics. [01]: https://json-schema.org/understanding-json-schema/reference/null.html#null
michaeltlombardi
added a commit
to michaeltlombardi/DSC
that referenced
this pull request
Aug 31, 2023
This change updates the `Microsoft/OSInfo` resource based on the work for documenting it in MicrosoftDocs/PowerShell-Docs-DSC#181 This change: - Minimally modifies the README for grammar and formatting. - Adds docs strings to the types in the source code. - Adds a canonical schema for the resource, and a YAML version of the schema for easier reading and maintaining. - Updates the resource manifest to embed the canonical schema. The canonical schema is generated from the YAML version using the following command: ```powershell $YamlPath = Resolve-Path -Path .\schemas\resources\Microsoft\OSInfo\v0.1.0\schema.yaml | Select-Object -ExpandProperty Path $JsonPath = $YamlPath -replace '\.yaml$', '.json' $Schema = Get-Content -Raw -Path $YamlPath | ConvertFrom-Yaml $Schema.'$id' = $Schema.'$id' -replace '\.yaml$', '.json' $Schema | ConvertTo-Json -Depth 100 | Out-File -Encoding utf8 -Path $JsonPath -Force ``` The schema uses the first sentence from the documentation as the value for the `description` keyword for each property, replacing backticks with single quotes, as the `description` keyword doesn't reliably render as Markdown for editors that support hover help for JSON schemas. After every description string is the link to that property in the documentation. The `markdownDescription` is a non-standard keyword supported by the JSON and YAML language servers in VS Code. When it's a non-empty string for a schema or subschema, it's rendered and used in the hover text instead of the `description` keyword. The other major change in the schema is to replace the semantically incorrect multi-type of `null` and `string` with a single type of `string`. The [JSON schema documentation][01] states: > It's important to remember that in JSON, null isn't equivalent to > something being absent. For JSON schemas, the `required` keyword indicates whether a property is required. By convention, if a property isn't required and isn't intended to be semantically `null`, it should be omitted from the JSON representation of the object instance. Using `null` in a multi-type should be reserved for when a `null` value carries specific semantics. [01]: https://json-schema.org/understanding-json-schema/reference/null.html#null
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
PR Summary
This change adds reference documentation for the proof-of-concept prototype command-based DSC Resources
Microsoft/OSInfoandMicrosoft.Windows/Registry.The reference documentation proposes a structure for the reference documentation for command-based resources based on the reference documentation used for the PSDscResources in v2.
It also documents the command-line tools the resources use.
While these commands and resources are not production-ready, they are the only command-based resources we can reference in the documentation at this time. If the resources are removed or replaced in the future, the documentation can be updated.
This change:
PR Checklist