Skip to content

Commit 2cd76ce

Browse files
PlagueHOPlagueHO
authored
Add Autodocumentation Generation - Fixes #110 (#111)
* Add Autodocumentation Generation - Issue #110 * Fix issue with MOF
1 parent 663a3ad commit 2cd76ce

File tree

11 files changed

+230
-27
lines changed

11 files changed

+230
-27
lines changed

‎.gitattributes

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,3 +2,9 @@
22
# Set default behavior to automatically normalize line endings.
33
###############################################################################
44
* text eol=crlf
5+
6+
# Ensure any exe files are treated as binary
7+
*.exe binary
8+
*.jpg binary
9+
*.xl* binary
10+
*.pfx binary

‎.gitignore

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22
*.user
33
*.coverage
44
.vs
5+
.vscode
56
.psproj
67
.sln
78
markdownissues.txt

‎.vscode/analyzersettings.psd1

Lines changed: 2 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,6 @@
11
@{
2-
<#
3-
For the custom rules to work, the DscResource.Tests repo must be
4-
cloned. It is automatically clone as soon as any unit or
5-
integration tests are run.
6-
#>
7-
CustomRulePath = '.\DSCResource.Tests\DscResource.AnalyzerRules'
8-
2+
CustomRulePath = '.\output\RequiredModules\DscResource.AnalyzerRules'
3+
includeDefaultRules = $true
94
IncludeRules = @(
105
# DSC Resource Kit style guideline rules.
116
'PSAvoidDefaultValueForMandatoryParameter',
@@ -43,11 +38,6 @@
4338
'PSUseDeclaredVarsMoreThanAssignments',
4439
'PSUsePSCredentialType',
4540

46-
<#
47-
This is to test all the DSC Resource Kit custom rules.
48-
The name of the function-blocks of each custom rule start
49-
with 'Measure*'.
50-
#>
5141
'Measure-*'
5242
)
5343
}

‎.vscode/settings.json

Lines changed: 25 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,6 @@
1-
// Place your settings in this file to overwrite default and user settings.
21
{
32
"powershell.codeFormatting.openBraceOnSameLine": false,
4-
"powershell.codeFormatting.newLineAfterOpenBrace": false,
3+
"powershell.codeFormatting.newLineAfterOpenBrace": true,
54
"powershell.codeFormatting.newLineAfterCloseBrace": true,
65
"powershell.codeFormatting.whitespaceBeforeOpenBrace": true,
76
"powershell.codeFormatting.whitespaceBeforeOpenParen": true,
@@ -10,7 +9,30 @@
109
"powershell.codeFormatting.ignoreOneLineBlock": false,
1110
"powershell.codeFormatting.pipelineIndentationStyle": "IncreaseIndentationAfterEveryPipeline",
1211
"powershell.codeFormatting.preset": "Custom",
12+
"powershell.codeFormatting.alignPropertyValuePairs": true,
1313
"files.trimTrailingWhitespace": true,
1414
"files.insertFinalNewline": true,
15-
"powershell.scriptAnalysis.settingsPath": ".vscode\\analyzersettings.psd1"
15+
"powershell.scriptAnalysis.settingsPath": ".vscode\\analyzersettings.psd1",
16+
"powershell.scriptAnalysis.enable": true,
17+
"files.associations": {
18+
"*.ps1xml": "xml"
19+
},
20+
"cSpell.words": [
21+
"COMPANYNAME",
22+
"ICONURI",
23+
"LICENSEURI",
24+
"PROJECTURI",
25+
"RELEASENOTES",
26+
"buildhelpers",
27+
"endregion",
28+
"gitversion",
29+
"icontains",
30+
"keepachangelog",
31+
"notin",
32+
"pscmdlet",
33+
"steppable"
34+
],
35+
"[markdown]": {
36+
"files.encoding": "utf8"
37+
}
1638
}

‎.vscode/tasks.json

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
{
2+
"version": "2.0.0",
3+
"_runner": "terminal",
4+
"windows": {
5+
"options": {
6+
"shell": {
7+
"executable": "C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe",
8+
"args": [
9+
"-NoProfile",
10+
"-ExecutionPolicy",
11+
"Bypass",
12+
"-Command"
13+
]
14+
}
15+
}
16+
},
17+
"linux": {
18+
"options": {
19+
"shell": {
20+
"executable": "/usr/bin/pwsh",
21+
"args": [
22+
"-NoProfile",
23+
"-Command"
24+
]
25+
}
26+
}
27+
},
28+
"osx": {
29+
"options": {
30+
"shell": {
31+
"executable": "/usr/local/bin/pwsh",
32+
"args": [
33+
"-NoProfile",
34+
"-Command"
35+
]
36+
}
37+
}
38+
},
39+
"tasks": [
40+
{
41+
"label": "build",
42+
"type": "shell",
43+
"command": "&${cwd}/build.ps1",
44+
"args": ["-AutoRestore"],
45+
"presentation": {
46+
"echo": true,
47+
"reveal": "always",
48+
"focus": true,
49+
"panel": "new",
50+
"clear": false
51+
},
52+
"runOptions": {
53+
"runOn": "default"
54+
},
55+
"problemMatcher": [
56+
{
57+
"owner": "powershell",
58+
"fileLocation": [
59+
"absolute"
60+
],
61+
"severity": "error",
62+
"pattern": [
63+
{
64+
"regexp": "^\\s*(\\[-\\]\\s*.*?)(\\d+)ms\\s*$",
65+
"message": 1
66+
},
67+
{
68+
"regexp": "(.*)",
69+
"code": 1
70+
},
71+
{
72+
"regexp": ""
73+
},
74+
{
75+
"regexp": "^.*,\\s*(.*):\\s*line\\s*(\\d+).*",
76+
"file": 1,
77+
"line": 2
78+
}
79+
]
80+
}
81+
]
82+
},
83+
{
84+
"label": "test",
85+
"type": "shell",
86+
"command": "&${cwd}/build.ps1",
87+
"args": ["-AutoRestore","-Tasks","test"],
88+
"presentation": {
89+
"echo": true,
90+
"reveal": "always",
91+
"focus": true,
92+
"panel": "dedicated",
93+
"showReuseMessage": true,
94+
"clear": false
95+
},
96+
"problemMatcher": [
97+
{
98+
"owner": "powershell",
99+
"fileLocation": [
100+
"absolute"
101+
],
102+
"severity": "error",
103+
"pattern": [
104+
{
105+
"regexp": "^\\s*(\\[-\\]\\s*.*?)(\\d+)ms\\s*$",
106+
"message": 1
107+
},
108+
{
109+
"regexp": "(.*)",
110+
"code": 1
111+
},
112+
{
113+
"regexp": ""
114+
},
115+
{
116+
"regexp": "^.*,\\s*(.*):\\s*line\\s*(\\d+).*",
117+
"file": 1,
118+
"line": 2
119+
}
120+
]
121+
}
122+
]
123+
}
124+
]
125+
}

‎CHANGELOG.md

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,3 +21,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
2121
- Updated to use continuous delivery pattern using Azure DevOps - Fixes
2222
[Issue #105](https://github.com/dsccommunity/ActiveDirectoryCSDsc/issues/105).
2323
- Fixed build badge IDs - Fixes [Issue #108](https://github.com/dsccommunity/ActiveDirectoryCSDsc/issues/108).
24+
- Corrected MOF formatting of `DSC_AdcsAuthorityInformationAccess.schema.mof`
25+
to fix issue with auto documentation generation.
26+
27+
### Added
28+
29+
- Added build task `Generate_Conceptual_Help` to generate conceptual help
30+
for the DSC resource.
31+
- Added build task `Generate_Wiki_Content` to generate the wiki content
32+
that can be used to update the GitHub Wiki.
33+
34+
### Changed
35+
36+
- Updated CI pipeline files.
37+
- No longer run integration tests when running the build task `test`, e.g.
38+
`.\build.ps1 -Task test`. To manually run integration tests, run the
39+
following:
40+
```powershell
41+
.\build.ps1 -Tasks test -PesterScript 'tests/Integration' -CodeCoverageThreshold 0
42+
```

‎CONTRIBUTING.md

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# Contributing
2+
3+
Please check out common DSC Community [contributing guidelines](https://dsccommunity.org/guidelines/contributing).
4+
5+
## Running the Tests
6+
7+
If want to know how to run this module's tests you can look at the [Testing Guidelines](https://dsccommunity.org/guidelines/testing-guidelines/#running-tests)

‎RequiredModules.psd1

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,22 @@
11
@{
2-
# Set up a mini virtual environment...
32
PSDependOptions = @{
43
AddToPath = $true
54
Target = 'output\RequiredModules'
65
Parameters = @{
6+
Repository = ''
77
}
88
}
99

10-
invokeBuild = 'latest'
10+
InvokeBuild = 'latest'
1111
PSScriptAnalyzer = 'latest'
12-
pester = 'latest'
12+
Pester = 'latest'
1313
Plaster = 'latest'
1414
ModuleBuilder = '1.0.0'
1515
ChangelogManagement = 'latest'
1616
Sampler = 'latest'
17+
MarkdownLinkCheck = 'latest'
1718
'DscResource.Test' = 'latest'
1819
'DscResource.AnalyzerRules' = 'latest'
20+
'DscResource.DocGenerator' = 'latest'
1921
xDscResourceDesigner = 'latest'
2022
}

‎build.ps1

Lines changed: 35 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ param
1818
[validateScript(
1919
{ Test-Path -Path $_ }
2020
)]
21-
$BuildConfig = './build.yaml',
21+
$BuildConfig,
2222

2323
[Parameter()]
2424
# A Specific folder to build the artefact into.
@@ -35,26 +35,37 @@ param
3535
[Parameter()]
3636
$RequiredModulesDirectory = $(Join-Path 'output' 'RequiredModules'),
3737

38+
[Parameter()]
39+
[object[]]
40+
$PesterScript,
41+
3842
# Filter which tags to run when invoking Pester tests
3943
# This is used in the Invoke-Pester.pester.build.ps1 tasks
4044
[Parameter()]
4145
[string[]]
4246
$PesterTag,
4347

44-
[Parameter()]
45-
[string[]]
46-
$PesterScript,
47-
4848
# Filter which tags to exclude when invoking Pester tests
4949
# This is used in the Invoke-Pester.pester.build.ps1 tasks
5050
[Parameter()]
5151
[string[]]
5252
$PesterExcludeTag,
5353

54+
# Filter which tags to run when invoking DSC Resource tests
55+
# This is used in the DscResource.Test.build.ps1 tasks
56+
[Parameter()]
57+
[string[]]
58+
$DscTestTag,
59+
60+
# Filter which tags to exclude when invoking DSC Resource tests
61+
# This is used in the DscResource.Test.build.ps1 tasks
62+
[Parameter()]
63+
[string[]]
64+
$DscTestExcludeTag,
65+
5466
[Parameter()]
5567
[Alias('bootstrap')]
56-
[switch]
57-
$ResolveDependency,
68+
[switch]$ResolveDependency,
5869

5970
[Parameter(DontShow)]
6071
[AllowNull()]
@@ -211,6 +222,22 @@ process
211222

212223
Begin
213224
{
225+
# Find build config if not specified
226+
if (-not $BuildConfig) {
227+
$config = Get-ChildItem -Path "$PSScriptRoot\*" -Include 'build.y*ml', 'build.psd1', 'build.json*' -ErrorAction:Ignore
228+
if (-not $config -or ($config -is [array] -and $config.Length -le 0)) {
229+
throw "No build configuration found. Specify path via -BuildConfig"
230+
}
231+
elseif ($config -is [array]) {
232+
if ($config.Length -gt 1) {
233+
throw "More than one build configuration found. Specify which one to use via -BuildConfig"
234+
}
235+
$BuildConfig = $config[0]
236+
}
237+
else {
238+
$BuildConfig = $config
239+
}
240+
}
214241
# Bootstrapping the environment before using Invoke-Build as task runner
215242

216243
if ($MyInvocation.ScriptName -notLike '*Invoke-Build.ps1')
@@ -309,7 +336,7 @@ Begin
309336
# If BuildConfig is a Yaml file, bootstrap powershell-yaml via ResolveDependency
310337
if ($BuildConfig -match '\.[yaml|yml]$')
311338
{
312-
$ResolveDependencyParams.add('WithYaml', $true)
339+
$ResolveDependencyParams.add('WithYaml', $True)
313340
}
314341

315342
$ResolveDependencyAvailableParams = (Get-Command -Name '.\Resolve-Dependency.ps1').parameters.keys

‎build.yaml

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,8 @@ BuildWorkflow:
2222
- Build_Module_ModuleBuilder
2323
- Build_NestedModules_ModuleBuilder
2424
- Create_changelog_release_output
25+
- Generate_Conceptual_Help
26+
- Generate_Wiki_Content
2527

2628
pack:
2729
- build
@@ -68,6 +70,8 @@ Resolve-Dependency:
6870
ModuleBuildTasks:
6971
Sampler:
7072
- '*.build.Sampler.ib.tasks'
73+
DscResource.DocGenerator:
74+
- 'Task.*'
7175

7276
TaskHeader: |
7377
param($Path)

0 commit comments

Comments
 (0)