Skip to content

Commit

Permalink
Add support for Auto Documentation - Fixes #677 (#728)
Browse files Browse the repository at this point in the history
  • Loading branch information
PlagueHO authored Sep 25, 2021
1 parent 475885c commit d13647a
Show file tree
Hide file tree
Showing 136 changed files with 1,260 additions and 2,104 deletions.
6 changes: 6 additions & 0 deletions .gitattributes
Original file line number Diff line number Diff line change
Expand Up @@ -2,3 +2,9 @@
# Set default behavior to automatically normalize line endings.
###############################################################################
* text eol=crlf

# Ensure any exe files are treated as binary
*.exe binary
*.jpg binary
*.xl* binary
*.pfx binary
2 changes: 1 addition & 1 deletion .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,8 @@
*.user
*.coverage
.vs
.vscode
.psproj
.sln
markdownissues.txt
TestResults.xml
output/
13 changes: 2 additions & 11 deletions .vscode/analyzersettings.psd1
Original file line number Diff line number Diff line change
@@ -1,10 +1,6 @@
@{
<#
For the custom rules to work, the DscResource.Tests repo must be
cloned. It is automatically clone as soon as any unit or
integration tests are run.
#>
CustomRulePath = '.\DSCResource.Tests\DscResource.AnalyzerRules'
CustomRulePath = '.\output\RequiredModules\DscResource.AnalyzerRules'
includeDefaultRules = $true

IncludeRules = @(
# DSC Resource Kit style guideline rules.
Expand Down Expand Up @@ -43,11 +39,6 @@
'PSUseDeclaredVarsMoreThanAssignments',
'PSUsePSCredentialType',

<#
This is to test all the DSC Resource Kit custom rules.
The name of the function-blocks of each custom rule start
with 'Measure*'.
#>
'Measure-*'
)
}
1 change: 1 addition & 0 deletions .vscode/settings.json
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@
"powershell.codeFormatting.whitespaceAroundOperator": true,
"powershell.codeFormatting.whitespaceAfterSeparator": true,
"powershell.codeFormatting.ignoreOneLineBlock": false,
"powershell.codeFormatting.pipelineIndentationStyle": "IncreaseIndentationForFirstPipeline",
"powershell.codeFormatting.preset": "Custom",
"files.trimTrailingWhitespace": true,
"files.insertFinalNewline": true,
Expand Down
6 changes: 6 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- Improved integration test reliability by resetting the DSC LCM
before executing each test using the `Reset-DscLcm`
function - Fixes [Issue #686](https://github.com/dsccommunity/xPSDesiredStateConfiguration/issues/686).
- Added build task `Generate_Conceptual_Help` to generate conceptual help
for the DSC resource - Fixes [Issue #677](https://github.com/dsccommunity/xPSDesiredStateConfiguration/issues/677).
- Added build task `Generate_Wiki_Content` to generate the wiki content
that can be used to update the GitHub Wiki - Fixes [Issue #677](https://github.com/dsccommunity/xPSDesiredStateConfiguration/issues/677).
- xDSCWebService:
- Moved strings into localization file - Fixes [Issue #622](https://github.com/dsccommunity/xPSDesiredStateConfiguration/issues/622).
- Corrected case of `CertificateThumbPrint` to `CertificateThumbprint`.
Expand All @@ -38,6 +42,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- Updated build to use `Sampler.GitHubTasks` - Fixes [Issue #711](https://github.com/dsccommunity/xPSDesiredStateConfiguration/issues/711).
- Added support for publishing code coverage to `CodeCov.io` and
Azure Pipelines - Fixes [Issue #711](https://github.com/dsccommunity/xPSDesiredStateConfiguration/issues/711).
- Updated vmImage used for build stage of CI to use `Windows-2019` to resolve
issues with Wiki Generation of `xUploadFile` composite resource on Linux agents.

## [9.1.0] - 2020-02-19

Expand Down
8 changes: 8 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
# Contributing

Please check out common DSC Community [contributing guidelines](https://dsccommunity.org/guidelines/contributing).

## Running the Tests

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).
1,175 changes: 51 additions & 1,124 deletions README.md

Large diffs are not rendered by default.

2 changes: 2 additions & 0 deletions RequiredModules.psd1
Original file line number Diff line number Diff line change
Expand Up @@ -13,9 +13,11 @@
ModuleBuilder = 'latest'
ChangelogManagement = 'latest'
Sampler = 'latest'
MarkdownLinkCheck = 'latest'
'Sampler.GitHubTasks' = 'latest'
'DscResource.Test' = 'latest'
'DscResource.AnalyzerRules' = 'latest'
'DscResource.DocGenerator' = 'latest'
'DscResource.Common' = 'latest'
xDscResourceDesigner = 'latest'
NetworkingDsc = '7.4.0.0'
Expand Down
6 changes: 3 additions & 3 deletions azure-pipelines.yml
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ stages:
- job: Package_Module
displayName: 'Package Module'
pool:
vmImage: 'ubuntu 16.04'
vmImage: 'windows-2019'
steps:
- task: GitVersion@5
name: gitversion
Expand Down Expand Up @@ -123,7 +123,7 @@ stages:
displayName: 'Publish Code Coverage'
dependsOn: Test_Unit_2016
pool:
vmImage: 'ubuntu 16.04'
vmImage: 'ubuntu-16.04'
timeoutInMinutes: 0
steps:
- task: DownloadPipelineArtifact@2
Expand Down Expand Up @@ -269,7 +269,7 @@ stages:
- job: Deploy_Module
displayName: 'Deploy Module'
pool:
vmImage: 'ubuntu 16.04'
vmImage: 'ubuntu-16.04'
steps:
- task: DownloadPipelineArtifact@2
displayName: 'Download Pipeline Artifact'
Expand Down
40 changes: 34 additions & 6 deletions build.ps1
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ param
[validateScript(
{ Test-Path -Path $_ }
)]
$BuildConfig = './build.yaml',
$BuildConfig,

[Parameter()]
# A Specific folder to build the artefact into.
Expand All @@ -35,22 +35,34 @@ param
[Parameter()]
$RequiredModulesDirectory = $(Join-Path 'output' 'RequiredModules'),

[Parameter()]
[object[]]
$PesterScript,

# Filter which tags to run when invoking Pester tests
# This is used in the Invoke-Pester.pester.build.ps1 tasks
[Parameter()]
[string[]]
$PesterTag,

[Parameter()]
[string[]]
$PesterScript,

# Filter which tags to exclude when invoking Pester tests
# This is used in the Invoke-Pester.pester.build.ps1 tasks
[Parameter()]
[string[]]
$PesterExcludeTag,

# Filter which tags to run when invoking DSC Resource tests
# This is used in the DscResource.Test.build.ps1 tasks
[Parameter()]
[string[]]
$DscTestTag,

# Filter which tags to exclude when invoking DSC Resource tests
# This is used in the DscResource.Test.build.ps1 tasks
[Parameter()]
[string[]]
$DscTestExcludeTag,

[Parameter()]
[Alias('bootstrap')]
[switch]$ResolveDependency,
Expand Down Expand Up @@ -210,6 +222,22 @@ process

Begin
{
# Find build config if not specified
if (-not $BuildConfig) {
$config = Get-ChildItem -Path "$PSScriptRoot\*" -Include 'build.y*ml', 'build.psd1', 'build.json*' -ErrorAction:Ignore
if (-not $config -or ($config -is [array] -and $config.Length -le 0)) {
throw "No build configuration found. Specify path via -BuildConfig"
}
elseif ($config -is [array]) {
if ($config.Length -gt 1) {
throw "More than one build configuration found. Specify which one to use via -BuildConfig"
}
$BuildConfig = $config[0]
}
else {
$BuildConfig = $config
}
}
# Bootstrapping the environment before using Invoke-Build as task runner

if ($MyInvocation.ScriptName -notLike '*Invoke-Build.ps1')
Expand Down Expand Up @@ -308,7 +336,7 @@ Begin
# If BuildConfig is a Yaml file, bootstrap powershell-yaml via ResolveDependency
if ($BuildConfig -match '\.[yaml|yml]$')
{
$ResolveDependencyParams.add('WithYaml', $true)
$ResolveDependencyParams.add('WithYaml', $True)
}

$ResolveDependencyAvailableParams = (Get-Command -Name '.\Resolve-Dependency.ps1').parameters.keys
Expand Down
4 changes: 4 additions & 0 deletions build.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,8 @@ BuildWorkflow:
- Build_Module_ModuleBuilder
- Build_NestedModules_ModuleBuilder
- Create_changelog_release_output
- Generate_Conceptual_Help
- Generate_Wiki_Content

pack:
- build
Expand Down Expand Up @@ -87,6 +89,8 @@ ModuleBuildTasks:
- '*.build.Sampler.ib.tasks'
Sampler.GitHubTasks:
- '*.ib.tasks'
DscResource.DocGenerator:
- 'Task.*'

TaskHeader: |
param($Path)
Expand Down
2 changes: 1 addition & 1 deletion source/DSCResources/DSC_xArchive/DSC_xArchive.schema.mof
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ class DSC_xArchive : OMI_BaseResource
[Key, Description("The path to the archive file that should be expanded to or removed from the specified destination.")] String Path;
[Key, Description("The path where the specified archive file should be expanded to or removed from.")] String Destination;
[Write, Description("Specifies whether or not the expanded content of the archive file at the specified path should exist at the specified destination. To update the specified destination to have the expanded content of the archive file at the specified path, specify this property as Present. To remove the expanded content of the archive file at the specified path from the specified destination, specify this property as Absent. The default value is Present."), ValueMap{"Present", "Absent"}, Values{"Present", "Absent"}] String Ensure;
[Write, Description("Specifies whether or not to validate that a file at the destination with the same name as a file in the archive actually matches that corresponding file in the archive by the specified checksum method. If the file does not match and Ensure is specified as Present and Force is not specified, the resource will throw an error that the file at the desintation cannot be overwritten. If the file does not match and Ensure is specified as Present and Force is specified, the file at the desintation will be overwritten. If the file does not match and Ensure is specified as Absent, the file at the desintation will not be removed. The default value is false.")] Boolean Validate;
[Write, Description("Specifies whether or not to validate that a file at the destination with the same name as a file in the archive actually matches that corresponding file in the archive by the specified checksum method. If the file does not match and Ensure is specified as Present and Force is not specified, the resource will throw an error that the file at the destination cannot be overwritten. If the file does not match and Ensure is specified as Present and Force is specified, the file at the destination will be overwritten. If the file does not match and Ensure is specified as Absent, the file at the destination will not be removed. The default value is false.")] Boolean Validate;
[Write, Description("The Checksum method to use to validate whether or not a file at the destination with the same name as a file in the archive actually matches that corresponding file in the archive. An invalid argument exception will be thrown if Checksum is specified while Validate is specified as false. ModifiedDate will check that the LastWriteTime property of the file at the destination matches the LastWriteTime property of the file in the archive. CreatedDate will check that the CreationTime property of the file at the destination matches the CreationTime property of the file in the archive. SHA-1, SHA-256, and SHA-512 will check that the hash of the file at the destination by the specified SHA method matches the hash of the file in the archive by the specified SHA method. The default value is ModifiedDate.") ,ValueMap{"SHA-1", "SHA-256", "SHA-512", "CreatedDate", "ModifiedDate"}, Values{"SHA-1", "SHA-256", "SHA-512", "CreatedDate", "ModifiedDate"}] String Checksum;
[Write, Description("The credential of a user account with permissions to access the specified archive path and destination if needed.") ,EmbeddedInstance("MSFT_Credential")] String Credential;
[Write, Description("Specifies whether or not any existing files or directories at the destination with the same name as a file or directory in the archive should be overwritten to match the file or directory in the archive. When this property is false, an error will be thrown if an item at the destination needs to be overwritten. The default value is false.")] Boolean Force;
Expand Down
10 changes: 10 additions & 0 deletions source/DSCResources/DSC_xArchive/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
# Description

Provides a mechanism to expand an archive (.zip) file to a specific path or
remove an expanded archive (.zip) file from a specific path on a target node.

## Requirements

- The System.IO.Compression type assembly must be available on the machine.
- The System.IO.Compression.FileSystem type assembly must be available on the
machine.
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ class DSC_xArchive : OMI_BaseResource
[Key,Description("The path to the archive file that should be expanded to or removed from the specified destination.") : Amended] String Path;
[Key,Description("The path where the specified archive file should be expanded to or removed from.") : Amended] String Destination;
[Description("Specifies whether or not the expanded content of the archive file at the specified path should exist at the specified destination. To update the specified destination to have the expanded content of the archive file at the specified path, specify this property as Present. To remove the expanded content of the archive file at the specified path from the specified destination, specify this property as Absent. The default value is Present.") : Amended] String Ensure;
[Description("Specifies whether or not to validate that a file at the destination with the same name as a file in the archive actually matches that corresponding file in the archive by the specified checksum method. If the file does not match and Ensure is specified as Present and Force is not specified, the resource will throw an error that the file at the desintation cannot be overwritten. If the file does not match and Ensure is specified as Present and Force is specified, the file at the desintation will be overwritten. If the file does not match and Ensure is specified as Absent, the file at the desintation will not be removed. The default value is false.") : Amended] Boolean Validate;
[Description("Specifies whether or not to validate that a file at the destination with the same name as a file in the archive actually matches that corresponding file in the archive by the specified checksum method. If the file does not match and Ensure is specified as Present and Force is not specified, the resource will throw an error that the file at the destination cannot be overwritten. If the file does not match and Ensure is specified as Present and Force is specified, the file at the destination will be overwritten. If the file does not match and Ensure is specified as Absent, the file at the destination will not be removed. The default value is false.") : Amended] Boolean Validate;
[Description("The Checksum method to use to validate whether or not a file at the destination with the same name as a file in the archive actually matches that corresponding file in the archive. An invalid argument exception will be thrown if Checksum is specified while Validate is specified as false. ModifiedDate will check that the LastWriteTime property of the file at the destination matches the LastWriteTime property of the file in the archive. CreatedDate will check that the CreationTime property of the file at the destination matches the CreationTime property of the file in the archive. SHA-1, SHA-256, and SHA-512 will check that the hash of the file at the destination by the specified SHA method matches the hash of the file in the archive by the specified SHA method. The default value is ModifiedDate.") : Amended] String Checksum;
[Description("The credential of a user account with permissions to access the specified archive path and destination if needed.") : Amended] String Credential;
[Description("Specifies whether or not any existing files or directories at the destination with the same name as a file or directory in the archive should be overwritten to match the file or directory in the archive. When this property is false, an error will be thrown if an item at the destination needs to be overwritten. The default value is false.") : Amended] Boolean Force;
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,7 @@ ConvertFrom-StringData @'
PathDoesNotContainValidPSDriveRoot = The path "{0}" cannot be accessed because it does not contain any directories to use as the root of a PSDrive.
ErrorCreatingPSDrive = An error occurred while attempting to create a PSDrive to access the path "{0}" under the user "{1}".
PathDoesNotExistAsLeaf = The path "{0}" does not exist or is not a path leaf.
DestinationExistsAsFile = A file exists at the desintation path "{0}".
DestinationExistsAsFile = A file exists at the destination path "{0}".
ErrorOpeningArchive = An error occurred while attempting to open the archive at path "{0}".
ErrorCopyingFromArchiveToDestination = An error occurred while attempting copy from the archive to the destination path "{0}".
DirectoryIsNotEmpty = The directory at path "{0}" is not empty, so it will not be removed.
Expand Down
12 changes: 6 additions & 6 deletions source/DSCResources/DSC_xDSCWebService/DSC_xDSCWebService.psm1
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ $script:localizedData = Get-LocalizedData -DefaultUICulture 'en-US'
Prefix of the WCF SVC file.
.PARAMETER ApplicationPoolName
The IIS ApplicationPool to use for the Pull Server. If not specified a
The IIS Application Pool to use for the Pull Server. If not specified a
pool with name 'PSWS' will be created.
.PARAMETER CertificateSubject
Expand All @@ -41,7 +41,7 @@ $script:localizedData = Get-LocalizedData -DefaultUICulture 'en-US'
The thumbprint of the Certificate in CERT:\LocalMachine\MY\ for Pull Server.
.PARAMETER ConfigureFirewall
Enable incomming firewall exceptions for the configured DSC Pull Server
Enable incoming firewall exceptions for the configured DSC Pull Server
port. Defaults to true.
.PARAMETER DisableSecurityBestPractices
Expand Down Expand Up @@ -259,7 +259,7 @@ function Get-TargetResource
Specifies is self-signed certs will be accepted for client authentication.
.PARAMETER ApplicationPoolName
The IIS ApplicationPool to use for the Pull Server. If not specified a
The IIS Application Pool to use for the Pull Server. If not specified a
pool with name 'PSWS' will be created.
.PARAMETER CertificateSubject
Expand All @@ -276,7 +276,7 @@ function Get-TargetResource
The location on the disk where the Configuration is stored.
.PARAMETER ConfigureFirewall
Enable incomming firewall exceptions for the configured DSC Pull Server
Enable incoming firewall exceptions for the configured DSC Pull Server
port. Defaults to true.
.PARAMETER DatabasePath
Expand Down Expand Up @@ -622,7 +622,7 @@ function Set-TargetResource
Specifies is self-signed certs will be accepted for client authentication.
.PARAMETER ApplicationPoolName
The IIS ApplicationPool to use for the Pull Server. If not specified a
The IIS Application Pool to use for the Pull Server. If not specified a
pool with name 'PSWS' will be created.
.PARAMETER CertificateSubject
Expand All @@ -639,7 +639,7 @@ function Set-TargetResource
The location on the disk where the Configuration is stored.
.PARAMETER ConfigureFirewall
Enable incomming firewall exceptions for the configured DSC Pull Server
Enable incoming firewall exceptions for the configured DSC Pull Server
port. Defaults to true.
.PARAMETER DatabasePath
Expand Down
Loading

0 comments on commit d13647a

Please sign in to comment.