Skip to content

Commit 5a7f48d

Browse files
michaeltlombardimichaeltlombardi
committed
(DOCS) Document new and changed config functions
This change adds reference documentation and changelog entries for the new and updated configuration functions in DSC. It also: - Defines a few helper snippets for docs authoring, scoped to the Markdown files in the repository. - Adds maintainer comments to the changelog for using the snippets and for updating the changelog, particularly around releases.
1 parent 7404ad8 commit 5a7f48d

17 files changed

+1769
-150
lines changed

‎.vscode/docs.code-snippets

+186
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,186 @@
1+
{
2+
// Place your DSCv3 workspace snippets here. Each snippet is defined under a snippet name and has a scope, prefix, body and
3+
// description. Add comma separated ids of the languages where the snippet is applicable in the scope field. If scope
4+
// is left empty or omitted, the snippet gets applied to all languages. The prefix is what is
5+
// used to trigger the snippet and the body will be expanded and inserted. Possible variables are:
6+
// $1, $2 for tab stops, $0 for the final cursor position, and ${1:label}, ${2:another} for placeholders.
7+
// Placeholders with the same ids are connected.
8+
"Configuration function template": {
9+
"scope": "markdown",
10+
"prefix": "docs-config-func-template",
11+
"description": "Template for a DSC configuration function reference document",
12+
"isFileTemplate": true,
13+
"body": [
14+
"---",
15+
"description: Reference for the '${1:name}' DSC configuration document function",
16+
"ms.date: $CURRENT_MONTH/$CURRENT_DATE/$CURRENT_YEAR",
17+
"ms.topic: reference",
18+
"title: ${1:name}",
19+
"---",
20+
"",
21+
"# ${1:name}",
22+
"",
23+
"## Synopsis",
24+
"",
25+
"${2:One sentence description}",
26+
"",
27+
"## Syntax",
28+
"",
29+
"```Syntax",
30+
"${1:name}(${3:input syntax})",
31+
"```",
32+
"",
33+
"## Description",
34+
"",
35+
"The `${1:name}` function ${4:full description}.",
36+
"",
37+
"## Examples",
38+
"",
39+
"### Example 1 - ${5:example title}",
40+
"",
41+
"${6:example synopsis}",
42+
"",
43+
"```yaml",
44+
"# ${1:name}.example.1.dsc.config.yaml",
45+
"\\$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json",
46+
"resources:",
47+
"- name: ${7:descriptive resource name}",
48+
" type: Test/Echo",
49+
" properties:",
50+
" output: \"[${1:name}(${8:example input})]\"",
51+
"```",
52+
"",
53+
"```bash",
54+
"dsc config get --document ${1:name}.example.1.dsc.config.yaml",
55+
"```",
56+
"",
57+
"```yaml",
58+
"results:",
59+
"- name: ${7:descriptive resource name}",
60+
" type: Test/Echo",
61+
" result:",
62+
" actualState:",
63+
" output: ${9:example output}",
64+
"messages: []",
65+
"hadErrors: false",
66+
"```",
67+
"",
68+
"## Parameters",
69+
"",
70+
"### ${10:parameter name}",
71+
"",
72+
"${11:parameter description}",
73+
"",
74+
"```yaml",
75+
"Type: ${12:parameter type}",
76+
"Required: ${13:whether parameter is mandatory}",
77+
"MinimumCount: ${14:1}",
78+
"MaximumCount: ${15:1}",
79+
"```",
80+
"",
81+
"## Output",
82+
"",
83+
"${16:output description}",
84+
"",
85+
"```yaml",
86+
"Type: ${17:output type}",
87+
"```",
88+
"",
89+
"<!-- Link reference definitions -->",
90+
""
91+
]
92+
},
93+
"Configuration function example": {
94+
"scope": "markdown",
95+
"prefix": "docs-config-func-example",
96+
"description": "Add an example to a DSC configuration function reference document",
97+
"body": [
98+
"### Example ${1:exampleIndex} - ${2:example title}",
99+
"",
100+
"${3:example synopsis}",
101+
"",
102+
"```yaml",
103+
"# $TM_FILENAME_BASE.example.$1.dsc.config.yaml",
104+
"\\$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json",
105+
"resources:",
106+
"- name: ${4:descriptive resource name}",
107+
" type: Test/Echo",
108+
" properties:",
109+
" output: \"[$TM_FILENAME_BASE(${5:example input})]\"",
110+
"```",
111+
"",
112+
"```bash",
113+
"dsc config get --document ${TM_FILENAME_BASE}.example.$1.dsc.config.yaml",
114+
"```",
115+
"",
116+
"```yaml",
117+
"results:",
118+
"- name: $4",
119+
" type: Test/Echo",
120+
" result:",
121+
" actualState:",
122+
" output: ${6:example output}",
123+
"messages: []",
124+
"hadErrors: false",
125+
"```"
126+
]
127+
},
128+
"Changelog Entry": {
129+
"scope": "markdown",
130+
"prefix": "docs-changelog-entry-single-issue-pr",
131+
"description": "Template for a DSC changelog entry",
132+
"body": [
133+
"- ${1:Change description}",
134+
"",
135+
" <details><summary>Related work items</summary>",
136+
"",
137+
" - Issues: [#${2:related issue id}][#${2:related issue id}]",
138+
" - PRs: [#${3:related pull request id}][#${3:related pull request id}]",
139+
"",
140+
" <details>",
141+
""
142+
]
143+
}
144+
"Changelog Entry Multi Item": {
145+
"scope": "markdown",
146+
"prefix": "docs-changelog-entry-multi-issue-pr",
147+
"description": "Template for a DSC changelog entry",
148+
"body": [
149+
"- ${1:Change description}",
150+
"",
151+
" <details><summary>Related work items</summary>",
152+
"",
153+
" - Issues:",
154+
" - [#${2:related issue id}][#${2:related issue id}]",
155+
" - PRs:",
156+
" - [#${3:related pull request id}][#${3:related pull request id}]",
157+
"",
158+
" <details>",
159+
""
160+
]
161+
}
162+
"Changelog release heading": {
163+
"scope": "markdown",
164+
"prefix": "docs-changelog-release-heading",
165+
"description": "Template for a DSC changelog release heading",
166+
"body": [
167+
"## [${1:v3.0.0-${2:alpha.5}}][release-${1:v3.0.0-${2:alpha.5}}] - ${3:${CURRENT_YEAR}-${CURRENT_MONTH}-${CURRENT_DATE}}",
168+
"",
169+
"This section includes a summary of changes for the `${2:alpha.5}` release. For the full list of changes",
170+
"in this release, see the [diff on GitHub][compare-${1:v3.0.0-${2:alpha.5}}].",
171+
"",
172+
"<!-- Release links -->",
173+
"[release-${1:v3.0.0-${2:alpha.5}}]: https://github.com/PowerShell/DSC/releases/tag/${1:v3.0.0-${2:alpha.5}} \"Link to the DSC ${1:v3.0.0-${2:alpha.5}} release on GitHub\"",
174+
"[compare-${1:v3.0.0-${2:alpha.5}}]: https://github.com/PowerShell/DSC/compare/v3.0.0-alpha.4...${1:v3.0.0-${2:alpha.5}}"
175+
]
176+
177+
}
178+
"Github Work Item Link": {
179+
"scope": "markdown",
180+
"prefix": "docs-gh-link",
181+
"description": "Template for a DSC Github work item link",
182+
"body": [
183+
"[#${1:work item id}]: https://github.com/PowerShell/DSC/issues/${1:work item id}"
184+
]
185+
}
186+
}

0 commit comments

Comments
 (0)