From 93cc913eda173d393958c8c6e58a766215355dcd Mon Sep 17 00:00:00 2001 From: Bernie White Date: Thu, 7 Dec 2017 22:11:55 +0800 Subject: [PATCH] Release merge for v0.3.0 (#6) * Added vscode task for code coverage reporting * Updated CI metadata * Added vscode settings to exclude paths * Documentation updates * Updated Yaml processing to keep header order and allow header merging * Quality updates for unit testing * Added message strings * Fix to prevent Yaml block from being processed when not explictly used * Updated Title keyword processing to handle multiple definitions * Added SharePoint documentation example * Documentation updates * Minor documentation updates * Updated tasks.json to use new schema * Moved cmdlet help docs * Reorgansed docs for scaffolding with platyPS * Added documentation updates * Fix documentation links on readme * Minor update to error handling in BuildDocumentation * Dependency and version update preparing for next release * Update documentation build tasks * Update tests and error handling * Documentation updates * Correction to change log grammer * Updates to link external help * Added launch file for debugging * Further documentation updates * Updated change log and readme * Updates to help and remove -Path parameter which is for a future use case * Updates for cmdlet help * Improved code block handling * Updated documentation links * Updates to include about topics in document build process * Updated script to clean up old docs * Added cleanup of docs build path * Added common parameters * Added keyword about help * Merged into keywords document * Removed configuration data parameter for Invoke-PSDocument * Fix up build task to prevent matcher prompt * Updated documentation * Automatically create OutputPath if it doesn't exist * Added PSDocs.Dsc to build task * Preparing for v0.3.0 --- .codecov.yml | 2 +- .gitignore | 3 +- .vscode/launch.json | 45 +++ .vscode/settings.json | 10 + .vscode/tasks.json | 33 +- CHANGELOG.md | 26 ++ README.md | 100 ++++-- appveyor.yml | 2 +- docs/commands/.markdownlint.json | 5 + docs/commands/Invoke-DscNodeDocument.md | 30 -- docs/commands/Invoke-PSDocument.md | 11 - .../PSDocs.Dsc/en-US/Get-DscMofDocument.md | 67 ++++ .../en-US/Invoke-DscNodeDocument.md | 143 ++++++++ docs/commands/PSDocs.Dsc/en-US/PSDocs.Dsc.md | 23 ++ docs/commands/PSDocs/en-US/Document.md | 80 +++++ .../PSDocs/en-US/Get-PSDocumentHeader.md | 83 +++++ .../PSDocs/en-US/Import-PSDocumentTemplate.md | 65 ++++ .../PSDocs/en-US/Invoke-PSDocument.md | 165 +++++++++ docs/commands/PSDocs/en-US/PSDocs.md | 31 ++ docs/examples/SharePoint-config-output.md | 44 +++ docs/examples/Yaml-header-output.md | 4 + docs/keywords/Code.md | 45 --- docs/keywords/Document.md | 38 -- docs/keywords/Note.md | 46 --- .../PSDocs/en-US/about_PSDocs_Keywords.md | 335 ++++++++++++++++++ docs/keywords/Section.md | 76 ---- docs/keywords/Table.md | 28 -- docs/keywords/Warning.md | 46 --- docs/keywords/Yaml.md | 46 --- scripts/build-docs.ps1 | 37 ++ scripts/common.ps1 | 9 +- scripts/test.ps1 | 10 +- src/PSDocs.Dsc/PSDocs.Dsc.psd1 | 4 +- src/PSDocs.Dsc/PSDocs.Dsc.psm1 | 10 +- src/PSDocs/PSDocs.psd1 | 3 +- src/PSDocs/PSDocs.psm1 | 139 ++++++-- .../PSDocsProcessor/Markdown/Markdown.psm1 | 31 +- src/PSDocs/en-AU/PSDocs.Resources.psd1 | 2 + src/PSDocs/en-US/PSDocs.Resources.psd1 | 2 + .../PSDocs.Dsc.Common.Tests.ps1 | 43 ++- tests/PSDocs.Tests/PSDocs.Code.Tests.ps1 | 56 ++- tests/PSDocs.Tests/PSDocs.Section.Tests.ps1 | 29 ++ tests/PSDocs.Tests/PSDocs.Table.Tests.ps1 | 26 +- tests/PSDocs.Tests/PSDocs.Title.Tests.ps1 | 104 ++++++ tests/PSDocs.Tests/PSDocs.Warning.Tests.ps1 | 4 +- tests/PSDocs.Tests/PSDocs.Yaml.Tests.ps1 | 171 +++++++++ 46 files changed, 1859 insertions(+), 453 deletions(-) create mode 100644 .vscode/launch.json create mode 100644 .vscode/settings.json create mode 100644 CHANGELOG.md create mode 100644 docs/commands/.markdownlint.json delete mode 100644 docs/commands/Invoke-DscNodeDocument.md delete mode 100644 docs/commands/Invoke-PSDocument.md create mode 100644 docs/commands/PSDocs.Dsc/en-US/Get-DscMofDocument.md create mode 100644 docs/commands/PSDocs.Dsc/en-US/Invoke-DscNodeDocument.md create mode 100644 docs/commands/PSDocs.Dsc/en-US/PSDocs.Dsc.md create mode 100644 docs/commands/PSDocs/en-US/Document.md create mode 100644 docs/commands/PSDocs/en-US/Get-PSDocumentHeader.md create mode 100644 docs/commands/PSDocs/en-US/Import-PSDocumentTemplate.md create mode 100644 docs/commands/PSDocs/en-US/Invoke-PSDocument.md create mode 100644 docs/commands/PSDocs/en-US/PSDocs.md create mode 100644 docs/examples/SharePoint-config-output.md create mode 100644 docs/examples/Yaml-header-output.md delete mode 100644 docs/keywords/Code.md delete mode 100644 docs/keywords/Document.md delete mode 100644 docs/keywords/Note.md create mode 100644 docs/keywords/PSDocs/en-US/about_PSDocs_Keywords.md delete mode 100644 docs/keywords/Section.md delete mode 100644 docs/keywords/Table.md delete mode 100644 docs/keywords/Warning.md delete mode 100644 docs/keywords/Yaml.md create mode 100644 scripts/build-docs.ps1 create mode 100644 tests/PSDocs.Tests/PSDocs.Title.Tests.ps1 create mode 100644 tests/PSDocs.Tests/PSDocs.Yaml.Tests.ps1 diff --git a/.codecov.yml b/.codecov.yml index 9197246..3664af7 100644 --- a/.codecov.yml +++ b/.codecov.yml @@ -2,7 +2,7 @@ codecov: notify: require_ci_to_pass: no # dev should be the baseline for reporting - branch: dev + branch: master comment: layout: "reach, diff" diff --git a/.gitignore b/.gitignore index 3863e93..3650ade 100644 --- a/.gitignore +++ b/.gitignore @@ -6,4 +6,5 @@ /build/ /reports/ /**/*.user -/.vscode/settings.json \ No newline at end of file +/src/**/*-help.xml +/src/**/*.help.txt \ No newline at end of file diff --git a/.vscode/launch.json b/.vscode/launch.json new file mode 100644 index 0000000..c9a0336 --- /dev/null +++ b/.vscode/launch.json @@ -0,0 +1,45 @@ +{ + "version": "0.2.0", + "configurations": [ + { + "type": "PowerShell", + "request": "launch", + "name": "PowerShell Launch Current File", + "script": "${file}", + "args": [], + "cwd": "${file}" + }, + { + "type": "PowerShell", + "request": "launch", + "name": "PowerShell Launch Current File in Temporary Console", + "script": "${file}", + "args": [], + "cwd": "${file}", + "createTemporaryIntegratedConsole": true + }, + { + "type": "PowerShell", + "request": "launch", + "name": "PowerShell Launch Current File w/Args Prompt", + "script": "${file}", + "args": [ + "${command:SpecifyScriptArgs}" + ], + "cwd": "${file}" + }, + { + "type": "PowerShell", + "request": "attach", + "name": "PowerShell Attach to Host Process", + "processId": "${command:PickPSHostProcess}", + "runspaceId": 1 + }, + { + "type": "PowerShell", + "request": "launch", + "name": "PowerShell Interactive Session", + "cwd": "${workspaceRoot}" + } + ] +} \ No newline at end of file diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 0000000..c261470 --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,10 @@ +{ + "files.exclude": { + ".vs": true, + "artifacts": true, + "reports": true + }, + "search.exclude": { + "build": true + } +} \ No newline at end of file diff --git a/.vscode/tasks.json b/.vscode/tasks.json index 3eaf805..904039c 100644 --- a/.vscode/tasks.json +++ b/.vscode/tasks.json @@ -4,7 +4,7 @@ "version": "2.0.0", "tasks": [ { - "taskName": "test", + "label": "test", "type": "shell", "command": ".\\scripts\\test.ps1", "group": { @@ -14,13 +14,38 @@ "problemMatcher": [ "$pester" ] }, { - "taskName": "build", + "label": "coverage", "type": "shell", - "command": ".\\scripts\\build.ps1 -Clean -Module PSDocs", + "command": ".\\scripts\\test.ps1 -Clean -CodeCoverage", + "problemMatcher": [ "$pester" ] + }, + { + "label": "build", + "type": "shell", + "command": ".\\scripts\\build.ps1 -Clean -Module PSDocs,PSDocs.Dsc", "group": { "kind": "build", "isDefault": true - } + }, + "problemMatcher": [] + }, + { + "label": "build-docs", + "type": "shell", + "command": ".\\scripts\\build-docs.ps1", + "problemMatcher": [] + }, + { + "label": "scaffold-docs", + "type": "shell", + "command": ".\\scripts\\build-docs.ps1 -Scaffold", + "problemMatcher": [] + }, + { + "label": "clean", + "type": "shell", + "command": "Remove-Item -Path .\\build -Recurse -Force", + "problemMatcher": [] } ] } \ No newline at end of file diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..6fec1ea --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,26 @@ + +## Unreleased + +## v0.3.0 + +- Improved `Yaml` block handling to allow yaml header to be defined throughout the document and merged when multiple blocks are defined +- Improved cmdlet help +- Output path is automatically created by `Invoke-PSDocument` if it doesn't exist +- Fix to improve handling when `Title` block is used multiple times +- Fix to prevent yaml header being created when `Yaml` block is not used +- Code blocks now generate fenced sections instead of indented sections +- [Breaking change] The body of Code blocks are now no longer evaluated as an expression + - This change improves editing of document templates, allowing editors to complete valid PowerShell syntax + - Define an expression and the pipe the results to the Code keyword to dynamically generate the contents of a code block +- [Breaking change] `-ConfigurationData` parameter of `Invoke-PSDocument` has been removed while purpose and future use of the parameter is reconsidered + +## v0.2.0 + +- Added Desired State Configuration (DSC) extension module PSDocs.Dsc to generate markdown from DSC .mof files +- Moved markdown processor to a seperate module +- Fix handling of multi-line notes and warnings +- Added support to include documentation from external script file + +## v0.1.0 + +- Initial release \ No newline at end of file diff --git a/README.md b/README.md index 8959b53..98ae35b 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,5 @@ # PSDocs + A PowerShell module with commands to generate markdown from objects using PowerShell syntax. | AppVeyor (Windows) | Codecov (Windows) | @@ -6,34 +7,36 @@ A PowerShell module with commands to generate markdown from objects using PowerS | [![av-image][]][av-site] | [![cc-image][]][cc-site] | [av-image]: https://ci.appveyor.com/api/projects/status/pl7tu7ktue388n7s -[av-site]: https://ci.appveyor.com/project/BernieWhite/psdocs +[av-site]: https://ci.appveyor.com/project/BernieWhite/PSDocs [cc-image]: https://codecov.io/gh/BernieWhite/PSDocs/branch/master/graph/badge.svg [cc-site]: https://codecov.io/gh/BernieWhite/PSDocs ## Disclaimer + This project is to be considered a **proof-of-concept** and **not a supported Microsoft product**. ## Modules + The following modules are included in this repository. | Module | Description | Latest version | | ------ | ----------- | -------------- | -| PSDocs | Generate markdown from PowerShell | [v0.2.0][psg-psdocs] | -| PSDocs.Dsc | Extension for PSDocs to generate markdown from Desired State Configuration | [v0.2.0][psg-psdocsdsc] | +| PSDocs | Generate markdown from PowerShell | [v0.3.0][psg-psdocs] | +| PSDocs.Dsc | Extension for PSDocs to generate markdown from Desired State Configuration | [v0.3.0][psg-psdocsdsc] | [psg-psdocs]: https://www.powershellgallery.com/packages/PSDocs [psg-psdocsdsc]: https://www.powershellgallery.com/packages/PSDocs.Dsc ## Getting started -### 1. Prerequsits +### Prerequsits - Windows Management Framework (WMF) 5.0 or greater - .NET Framework 4.6 or greater -### 2. Get PSDocs +### Getting the modules -- Install from PowerShellGallery.com +- Install from [PowerShell Gallery][psg-psdocs] ```powershell # Install base PSDocs module @@ -45,15 +48,26 @@ Install-Module -Name 'PSDocs'; Install-Module -Name 'PSDocs.Dsc'; ``` -### 3. Usage +- Save for offline use from PowerShell Gallery + +```powershell +# Save PSDocs module, in the .\modules directory +Save-Module -Name 'PSDocs' -Path '.\modules'; + +# Save PSDocs.Dsc module, in the .\modules directory +Save-Module -Name 'PSDocs.Dsc' -Path '.\modules'; +``` + +### Generate a document from a directory listing ```powershell # Import PSDocs module Import-Module -Name PSDocs; -# Define a sample document -document Sample { +# Define a document called Sample +Document Sample { + # Add an introduction section Section Introduction { # Add a comment "This is a sample file list from $InputObject" @@ -63,28 +77,68 @@ document Sample { } } -# Call the sample document and generate markdown -Invoke-PSDocument -Name Sample -InputObject 'C:\'; +# Call the document definition and generate markdown from an object +Invoke-PSDocument -Name 'Sample' -InputObject 'C:\'; ``` -For an example of the output generated see [Get-ChildItemExample](/docs/examples/Get-child-item-output.md) +An example of the output generated is available [here](/docs/examples/Get-child-item-output.md). + +### Generate documentation from Desired State Configuration + +```powershell +# Import PSDocs.Dsc module +Import-Module -Name PSDocs.Dsc; + +# Define a document called Sample +Document 'Sample' { + + # Add an 'Installed features' section in the document + Section 'Installed features' { + # Add a comment + 'The following Windows features have been installed.' + + # Generate a table of Windows Features + $InputObject.ResourceType.WindowsFeature | Table -Property Name,Ensure + } +} + +# Call the document definition and generate markdown for each .mof file in the .\nodes directory +Invoke-DscNodeDocument -DocumentName 'Sample' -Path '.\nodes' -OutputPath '.\docs'; +``` ## Language reference +PSDocs extends PowerShell with domain specific lanagage (DSL) keywords and cmdlets. + ### Keywords -- [Document](/docs/keywords/Document.md) -- [Section](/docs/keywords/Section.md) -- [Code](/docs/keywords/Code.md) -- [Note](/docs/keywords/Note.md) -- [Warning](/docs/keywords/Warning.md) -- [Yaml](/docs/keywords/Yaml.md) -- [Table](/docs/keywords/Table.md) +The following language keywords are used by the `PSDocs` module: + +- [Document](/docs/keywords/PSDocs/en-US/Document.md) - Defines a named documentation block +- [Section](/docs/keywords/PSDocs/en-US/Section.md) - Creates a named section +- [Title](/docs/keywords/PSDocs/en-US/Title.md) - Sets the document title +- [Code](/docs/keywords/PSDocs/en-US/Code.md) - Inserts a block of code +- [Note](/docs/keywords/PSDocs/en-US/Note.md) - Inserts a note using DocFx formatted markdown (DFM) +- [Warning](/docs/keywords/PSDocs/en-US/Warning.md) - Inserts a warnding usinf DocFx formatted markdown (DFM) +- [Yaml](/docs/keywords/PSDocs/en-US/Yaml.md) - Inserts a YAML header +- [Table](/docs/keywords/PSDocs/en-US/Table.md) - Inserts a table from pipeline objects ### Commands -- [Invoke-PSDocument](/docs/commands/Invoke-PSDocument.md) -- [Invoke-DscNodeDocument](/docs/commands/Invoke-DscNodeDocument.md) +The following commands exist in the `PSDocs` module: + +- [Invoke-PSDocument](/docs/commands/PSDocs/en-US/Invoke-PSDocument.md) +- [Get-PSDocumentHeader](/docs/commands/PSDocs/en-US/Get-PSDocumentHeader.md) +- [Import-PSDocumentTemplate](/docs/commands/PSDocs/en-US/Import-PSDocumentTemplate.md) + +The following commands exist in the `PSDocs.Dsc` module: + +- [Get-DscMofDocument](/docs/commands/PSDocs.Dsc/en-US/Get-DscMofDocument.md) +- [Invoke-DscNodeDocument](/docs/commands/PSDocs.Dsc/en-US/Invoke-DscNodeDocument.md) + +## Changes and versioning + +Modules in this repository will use the [semantic versioning](http://semver.org/) model to delcare breaking changes from v1.0.0. Prior to v1.0.0, breaking changes may be introduced in minor (0.x.0) version increments. For a list of module changes please see the [change log](CHANGELOG.md). ## Maintainers @@ -92,4 +146,6 @@ For an example of the output generated see [Get-ChildItemExample](/docs/examples ## License -This project is [licensed under the MIT License](LICENSE). \ No newline at end of file +This project is [licensed under the MIT License](LICENSE). + +[psg-psdocs]: https://www.powershellgallery.com/packages/PSDocs \ No newline at end of file diff --git a/appveyor.yml b/appveyor.yml index 564eb62..3266a15 100644 --- a/appveyor.yml +++ b/appveyor.yml @@ -1,4 +1,4 @@ -version: 0.1.0.{build} +version: 0.3.0.{build} image: Visual Studio 2017 build: off test_script: diff --git a/docs/commands/.markdownlint.json b/docs/commands/.markdownlint.json new file mode 100644 index 0000000..487a9c2 --- /dev/null +++ b/docs/commands/.markdownlint.json @@ -0,0 +1,5 @@ +{ + "first-line-h1": false, + "line-length": false, + "no-bare-urls": false +} \ No newline at end of file diff --git a/docs/commands/Invoke-DscNodeDocument.md b/docs/commands/Invoke-DscNodeDocument.md deleted file mode 100644 index fbd89fa..0000000 --- a/docs/commands/Invoke-DscNodeDocument.md +++ /dev/null @@ -1,30 +0,0 @@ - -# Invoke-DscNodeDocument - -## SYNOPSIS -Calls a document definition. - -## SYNTAX - -``` -Invoke-DscNodeDocument -DocumentName [-Path ] [-OutputPath ] -``` - -## EXAMPLES - -### EXAMPLE 1 - -```powershell -Document 'Test' { - - Section 'Installed features' { - 'The following Windows features have been installed.' - - $InputObject.ResourceType.WindowsFeature | Table -Property Name,Ensure; - } -} - -Invoke-DscNodeDocument -DocumentName 'Test' -Path '.\nodes' -OutputPath '.\docs'; -``` - -Generates a new markdown document for each node .mof in the path `.\nodes`. diff --git a/docs/commands/Invoke-PSDocument.md b/docs/commands/Invoke-PSDocument.md deleted file mode 100644 index c11894d..0000000 --- a/docs/commands/Invoke-PSDocument.md +++ /dev/null @@ -1,11 +0,0 @@ - -# Invoke-PSDocument - -## SYNOPSIS -Calls a document definition. - -## SYNTAX - -``` -Invoke-PSDocument [-Name] [-InstanceName ] [-InputObject ] [-ConfigurationData ] [-Path ] [-OutputPath ] [-Function >] -``` diff --git a/docs/commands/PSDocs.Dsc/en-US/Get-DscMofDocument.md b/docs/commands/PSDocs.Dsc/en-US/Get-DscMofDocument.md new file mode 100644 index 0000000..6f52c7b --- /dev/null +++ b/docs/commands/PSDocs.Dsc/en-US/Get-DscMofDocument.md @@ -0,0 +1,67 @@ +--- +external help file: PSDocs.Dsc-help.xml +Module Name: PSDocs.Dsc +online version: https://github.com/BernieWhite/PSDocs/blob/master/docs/commands/PSDocs.Dsc/en-US/Get-DscMofDocument.md +schema: 2.0.0 +--- + +# Get-DscMofDocument + +## SYNOPSIS + +Get document graph from .mof file. + +## SYNTAX + +```text +Get-DscMofDocument [-Path] [] +``` + +## DESCRIPTION + +Get a Managed Object Format (MOF) graph from a .mof file. + +This cmdlet will return a DscMofDocument object, containing ResourceId and ResourceType properties that enumerate Desired State Configuration (DSC) resources defined in the .mof file. + +## EXAMPLES + +### Example 1 + +```powershell +PS C:\> Get-DscMofDocument -Path '.\node1.mof'; +``` + +Get resources from a .mof file. + +## PARAMETERS + +### -Path + +The file path to a .mof file. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: True +Position: 0 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### None + +## OUTPUTS + +### DscMofDocument + +## NOTES + +## RELATED LINKS diff --git a/docs/commands/PSDocs.Dsc/en-US/Invoke-DscNodeDocument.md b/docs/commands/PSDocs.Dsc/en-US/Invoke-DscNodeDocument.md new file mode 100644 index 0000000..8906299 --- /dev/null +++ b/docs/commands/PSDocs.Dsc/en-US/Invoke-DscNodeDocument.md @@ -0,0 +1,143 @@ +--- +external help file: PSDocs.Dsc-help.xml +Module Name: PSDocs.Dsc +online version: https://github.com/BernieWhite/PSDocs/blob/master/docs/commands/PSDocs.Dsc/en-US/Invoke-DscNodeDocument.md +schema: 2.0.0 +--- + +# Invoke-DscNodeDocument + +## SYNOPSIS + +Create markdown from Desired State Configuration (DSC) .mof file. + +## SYNTAX + +```text +Invoke-DscNodeDocument [[-DocumentName] ] [[-Script] ] [[-InstanceName] ] + [[-Path] ] [[-OutputPath] ] [] +``` + +## DESCRIPTION + +Create markdown from Desired State Configuration (DSC) .mof file. + +## EXAMPLES + +### Example 1 + +```powershell +# Define a document called Sample +Document 'Sample' { + + # Add an 'Installed features' section in the document + Section 'Installed features' { + # Add a comment + 'The following Windows features have been installed.' + + # Generate a table of Windows Features + $InputObject.ResourceType.WindowsFeature | Table -Property Name,Ensure + } +} + +Invoke-DscNodeDocument -DocumentName 'Sample' -Path '.\nodes' -OutputPath '.\docs'; +``` + +Generates a new markdown document for each node .mof in the path '.\nodes'. + +## PARAMETERS + +### -DocumentName + +The name of the document template. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: 0 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -InstanceName + +The name(s) of the .mof instance to create markdown for. If this option is not specified, markdown will be created for all instances. + +```yaml +Type: String[] +Parameter Sets: (All) +Aliases: + +Required: False +Position: 2 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -OutputPath + +The directory path to store generated markdown files. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: 4 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Path + +The path to search for .mof files in. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: 3 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Script + +A file path to a script file containing the documentation template to use. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: 1 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### None + +## OUTPUTS + +### System.Object + +## NOTES + +## RELATED LINKS diff --git a/docs/commands/PSDocs.Dsc/en-US/PSDocs.Dsc.md b/docs/commands/PSDocs.Dsc/en-US/PSDocs.Dsc.md new file mode 100644 index 0000000..744bf01 --- /dev/null +++ b/docs/commands/PSDocs.Dsc/en-US/PSDocs.Dsc.md @@ -0,0 +1,23 @@ +--- +Module Name: PSDocs.Dsc +Module Guid: 9c6339e5-174f-447d-b7a7-7dd58ae9a13d +Download Help Link: https://github.com/BernieWhite/PSDocs +Help Version: 0.1.0.0 +Locale: en-US +--- + +# PSDocs.Dsc Module + +## Description + +Desired State Configuration (DSC) extensions for PSDocs. + +## PSDocs.Dsc Cmdlets + +### [Get-DscMofDocument](Get-DscMofDocument.md) + +Get document graph from .mof file. + +### [Invoke-DscNodeDocument](Invoke-DscNodeDocument.md) + +Create markdown from Desired State Configuration (DSC) .mof file. diff --git a/docs/commands/PSDocs/en-US/Document.md b/docs/commands/PSDocs/en-US/Document.md new file mode 100644 index 0000000..20aefde --- /dev/null +++ b/docs/commands/PSDocs/en-US/Document.md @@ -0,0 +1,80 @@ +--- +external help file: PSDocs-help.xml +Module Name: PSDocs +online version: https://github.com/BernieWhite/PSDocs/blob/master/docs/commands/PSDocs/en-US/Document.md +schema: 2.0.0 +--- + +# Document + +## SYNOPSIS + +Defines a named block that can be called to output documentation. + +## SYNTAX + +```text +Document [-Name] [-Body] +``` + +## DESCRIPTION + +Defines a named block that can be called to output documentation. + +## EXAMPLES + +### Example 1 + +```powershell +Document 'Test' { + # Insert content here +} +``` + +Define an empty document template called Test. + +## PARAMETERS + +### -Body + +A script block containing the document definition. + +```yaml +Type: ScriptBlock +Parameter Sets: (All) +Aliases: + +Required: True +Position: 1 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Name + +The name of the document. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: True +Position: 0 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +## INPUTS + +### None + +## OUTPUTS + +### System.Object + +## NOTES + +## RELATED LINKS diff --git a/docs/commands/PSDocs/en-US/Get-PSDocumentHeader.md b/docs/commands/PSDocs/en-US/Get-PSDocumentHeader.md new file mode 100644 index 0000000..e5d3404 --- /dev/null +++ b/docs/commands/PSDocs/en-US/Get-PSDocumentHeader.md @@ -0,0 +1,83 @@ +--- +external help file: PSDocs-help.xml +Module Name: PSDocs +online version: https://github.com/BernieWhite/PSDocs/blob/master/docs/commands/PSDocs/en-US/Get-PSDocumentHeader.md +schema: 2.0.0 +--- + +# Get-PSDocumentHeader + +## SYNOPSIS + +Get the Yaml header from a PSDocs generated markdown file. + +## SYNTAX + +```text +Get-PSDocumentHeader [[-Path] ] [] +``` + +## DESCRIPTION + +Get the Yaml header from a PSDocs generated markdown file. + +## EXAMPLES + +### Example 1 + +```powershell +PS C:\> Get-PSDocumentHeader -Path '.\build\Default'; +``` + +Get the Yaml header for all markdown files in the Default directory. + +### Example 2 + +```powershell +PS C:\> Get-PSDocumentHeader -Path '.\build\Default\Server1.md'; +``` + +Get the Yaml header for a specific file Server1.md. + +### Example 3 + +```powershell +PS C:\> Get-PSDocumentHeader; +``` + +Get the Yaml header for all markdown files in the current working directory. + +## PARAMETERS + +### -Path + +The path to a specific markdown file or a parent directory containing one or more markdown files. A trailing slash is not required. + +If a path is not specified the current working path will be used. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: FullName + +Required: False +Position: 0 +Default value: $PWD +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + +### CommonParameters +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### System.String + +## OUTPUTS + +### System.Object + +## NOTES + +## RELATED LINKS diff --git a/docs/commands/PSDocs/en-US/Import-PSDocumentTemplate.md b/docs/commands/PSDocs/en-US/Import-PSDocumentTemplate.md new file mode 100644 index 0000000..560c960 --- /dev/null +++ b/docs/commands/PSDocs/en-US/Import-PSDocumentTemplate.md @@ -0,0 +1,65 @@ +--- +external help file: PSDocs-help.xml +Module Name: PSDocs +online version: https://github.com/BernieWhite/PSDocs/blob/master/docs/commands/PSDocs/en-US/Import-PSDocumentTemplate.md +schema: 2.0.0 +--- + +# Import-PSDocumentTemplate + +## SYNOPSIS + +Import a document template script file into the current environment. + +## SYNTAX + +```text +Import-PSDocumentTemplate [-Path] [] +``` + +## DESCRIPTION + +Import a document template script file into the current environment. + +## EXAMPLES + +### Example 1 + +```powershell +PS C:\> Import-PSDocumentTemplate -Path '.\template.ps1'; +``` + +Imports a document template into the current environment. + +## PARAMETERS + +### -Path + +The file path to a script file containing a documentation template. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: True +Position: 0 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### None + +## OUTPUTS + +### System.Object + +## NOTES + +## RELATED LINKS diff --git a/docs/commands/PSDocs/en-US/Invoke-PSDocument.md b/docs/commands/PSDocs/en-US/Invoke-PSDocument.md new file mode 100644 index 0000000..147087a --- /dev/null +++ b/docs/commands/PSDocs/en-US/Invoke-PSDocument.md @@ -0,0 +1,165 @@ +--- +external help file: PSDocs-help.xml +Module Name: PSDocs +online version: https://github.com/BernieWhite/PSDocs/blob/master/docs/commands/PSDocs/en-US/Invoke-PSDocument.md +schema: 2.0.0 +--- + +# Invoke-PSDocument + +## SYNOPSIS + +Create markdown from an input object. + +## SYNTAX + +```text +Invoke-PSDocument [-Name] [-InstanceName ] [-InputObject ] [-OutputPath ] + [-Function ] + [-PassThru] [] +``` + +## DESCRIPTION + +Create markdown from an input object using a document definition. A document is defined using the Document keyword. + +## EXAMPLES + +### Example 1 + +```powershell +# Define a document called Sample +Document Sample { + + # Add an introduction section + Section Introduction { + + # Add a comment + "This is a sample file list from $InputObject" + + # Generate a table + Get-ChildItem -Path $InputObject | Table -Property Name,PSIsContainer + } +} + +Invoke-PSDocument -Name 'Sample' -InputObject 'C:\'; +``` + +Create markdown using the Sample documentation definition for 'C:\'. + +## PARAMETERS + +### -Function + +This option can be used to define documentation specific functions that can be used using markdown creation. + +```yaml +Type: System.Collections.Generic.Dictionary`2[System.String,System.Management.Automation.ScriptBlock] +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -InputObject + +An input object that will be used to build markdown. + +```yaml +Type: PSObject +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: True (ByValue) +Accept wildcard characters: False +``` + +### -InstanceName + +The name of the resulting markdown file. During execution of this command, the variable $InstanceName will be available within the document definition for use by expressions. + +If InstanceName is not specified the name of the document definition will be used instead. + +If more then one InstanceName is specified, multiple markdown files will be generated in the order they were specified. + +```yaml +Type: String[] +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Name + +The name of a specific document template to use to generate markdown. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: True +Position: 0 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -OutputPath + +The directory path to store markdown files created based on the specified document template. This path will be automatically created if it doesn't exist. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -PassThru + +When specified generated markdown will be returned to the pipeline instead of being written to file. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### System.Management.Automation.PSObject + +## OUTPUTS + +### System.Object + +## NOTES + +## RELATED LINKS diff --git a/docs/commands/PSDocs/en-US/PSDocs.md b/docs/commands/PSDocs/en-US/PSDocs.md new file mode 100644 index 0000000..6c5b6eb --- /dev/null +++ b/docs/commands/PSDocs/en-US/PSDocs.md @@ -0,0 +1,31 @@ +--- +Module Name: PSDocs +Module Guid: 1f6df554-c081-40d8-9aca-32c1abe4a1b6 +Download Help Link: https://github.com/BernieWhite/PSDocs +Help Version: 0.1.0.0 +Locale: en-US +--- + +# PSDocs Module + +## Description + +Generate markdown from PowerShell. + +## PSDocs Cmdlets + +### [Document](Document.md) + +Defines a named block that can be called to output documentation. + +### [Get-PSDocumentHeader](Get-PSDocumentHeader.md) + +Get the Yaml header from a PSDocs generated markdown file. + +### [Import-PSDocumentTemplate](Import-PSDocumentTemplate.md) + +{{Manually Enter Import-PSDocumentTemplate Description Here}} + +### [Invoke-PSDocument](Invoke-PSDocument.md) + +Create markdown from an input object. diff --git a/docs/examples/SharePoint-config-output.md b/docs/examples/SharePoint-config-output.md new file mode 100644 index 0000000..d90453b --- /dev/null +++ b/docs/examples/SharePoint-config-output.md @@ -0,0 +1,44 @@ +# Server1 + +## Installation + +|InstallerPath|OnlineMode| +| --- | --- | +|C:\\binaries\\prerequisiteinstaller.exe|True| + +|BinaryDir| +| --- | +|C:\\binaries\\| + +## Farm + +|DatabaseServer|FarmConfigDatabaseName|AdminContentDatabaseName| +| --- | --- | --- | +|sql.contoso.com|SP_Config|SP_AdminContent| + +## Installed services + +|Name|Ensure| +| --- | --- | +|Claims to Windows Token Service|Present| +|Secure Store Service|Present| +|SharePoint Server Search|Present| + +## Site +See the site configuration below. + +|Url|OwnerAlias|Name|Template| +| --- | --- | --- | --- | +|http://sites.contoso.com|CONTOSO\\SP_Admin|DSC Demo Site|STS#0| + +### Web applications + +|Name|Url|Port|HostHeader|ApplicationPool|AuthenticationMethod|AllowAnonymous| +| --- | --- | --- | --- | --- | --- | --- | +|SharePoint Sites|http://sites.contoso.com|80|sites.contoso.com|SharePoint Sites|NTLM|False| + +## Logging + +|LogPath|DaysToKeepLogs|LogCutInterval| +| --- | --- | --- | +|C:\\ULS|7|15| diff --git a/docs/examples/Yaml-header-output.md b/docs/examples/Yaml-header-output.md new file mode 100644 index 0000000..a7d1db5 --- /dev/null +++ b/docs/examples/Yaml-header-output.md @@ -0,0 +1,4 @@ +--- +title: An example title +--- +Yaml header may not be rendered by some markdown viewers. See source to view yaml. diff --git a/docs/keywords/Code.md b/docs/keywords/Code.md deleted file mode 100644 index 8150493..0000000 --- a/docs/keywords/Code.md +++ /dev/null @@ -1,45 +0,0 @@ - -# Code - -## SYNOPSIS -Creates a formatted code section. - -## SYNTAX - -``` -Code [-Body] -``` - -## EXAMPLES - -### EXAMPLE 1 - -```powershell -Document 'Test' { - - Code { - 'Get-Item -Path .\;' - } -} - -Invoke-PSDocument -Name 'Test' -InputObject $Null; -``` - -Generates a new Test.md document containing code. - -## PARAMETERS - -### -Body -A block of inline code to insert. - -```yaml -Type: ScriptBlock -Parameter Sets: (All) -Aliases: - -Required: True -Position: 1 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` diff --git a/docs/keywords/Document.md b/docs/keywords/Document.md deleted file mode 100644 index 991a1d0..0000000 --- a/docs/keywords/Document.md +++ /dev/null @@ -1,38 +0,0 @@ - -# Document - -## SYNOPSIS -Defines a named block that can be called to output documentation. - -## SYNTAX - -``` -Document [-Name] -``` - -## EXAMPLES - -### EXAMPLE 1 - -```powershell -Document 'Test' { - -} -``` - -## PARAMETERS - -### -Name -The name of the document. - -```yaml -Type: String -Parameter Sets: (All) -Aliases: - -Required: True -Position: 1 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` diff --git a/docs/keywords/Note.md b/docs/keywords/Note.md deleted file mode 100644 index bad1189..0000000 --- a/docs/keywords/Note.md +++ /dev/null @@ -1,46 +0,0 @@ - -# Note - -## SYNOPSIS -Creates a formatted note block. - -## SYNTAX - -``` -Note [-Body] -``` - -## EXAMPLES - -### EXAMPLE 1 - -```powershell -Document 'Test' { - - Note { - 'This is a note.' - } -} - -Invoke-PSDocument -Name 'Test'; -``` - -Generates a new Test.md document containing a block quote formatted as a DFM note. - - -## PARAMETERS - -### -Body -A block of inline text to insert. - -```yaml -Type: ScriptBlock -Parameter Sets: (All) -Aliases: - -Required: True -Position: 1 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` diff --git a/docs/keywords/PSDocs/en-US/about_PSDocs_Keywords.md b/docs/keywords/PSDocs/en-US/about_PSDocs_Keywords.md new file mode 100644 index 0000000..f36949e --- /dev/null +++ b/docs/keywords/PSDocs/en-US/about_PSDocs_Keywords.md @@ -0,0 +1,335 @@ +# PSDocs_Keywords + +## about_PSDocs_Keywords + +## SHORT DESCRIPTION + +Describes the language keywords that can be used within PSDocs document definitions. + +## LONG DESCRIPTION + +PSDocs lets you generate dynamic markdown documents using PowerShell blocks. To generate markdown a document is defined inline or within script files by using the `document` keyword. + +- Document - A named document definition +- Section - A named section +- Title - Sets the document title +- Code - Inserts a block of code +- Note - Inserts a note using DocFx formatted markdown (DFM) +- Warning - Inserts a warnding usinf DocFx formatted markdown (DFM) +- Table - Inserts a table from pipeline objects +- Yaml - Inserts a YAML header + +### Document + +Defines a named block that can be called to output documentation. The document keyword can be defined inline or in a seperate script file. + +Syntax: + +```text +Document [-Name] [-Body] +``` + +- `Name` - The name of the document definition. +- `Body` - A definition of the markdown document containing one or more PSDocs keywords and PowerShell. + +Examples: + +```powershell +# A document definition named Sample +Document 'Sample' { + + # Define the document here +} + +# Generate markdown from the document definition +Invoke-PSDocument -Name 'Sample' -InputObject ''; +``` + +### Section + +Creates a new document section block containing content. Each section will be converted into a header. + +Syntax: + +```text +Section [-Name] [-When ] [-Body] +``` + +- `Name` - The name or header of the section. +- `When` - A condition to determine if the section block should be included in the markdown document. + +Examples: + +```powershell +# A document definition named Sample +Document 'Sample' { + + # Define a section named Introduction + Section 'Intoduction' { + + # Content of the Introduction section + 'This is a sample document that uses PSDocs keywords to construct a dynamic document.' + + # Define more section content here + } +} + +# Generate markdown from the document definition +Invoke-PSDocument -Name 'Sample' -InputObject ''; +``` + +```powershell +# A document definition named Sample +Document 'Sample' { + + # Sections can be nested + Section 'Level2' { + + Section 'Level3' { + + # Define level 3 section content here + } + + # Define more level 2 section content here + } +} + +# Generate markdown from the document definition +Invoke-PSDocument -Name 'Sample' -InputObject ''; +``` + +```powershell +# A document definition named Sample +Document 'Sample' { + + # By default each section is included when markdown in generated + Section 'Included in output' { + + # SEction and section content is included in generated markdown + } + + # Sections can be optional if the When parameter is specified the expressnio evaluates to $False + Section 'Not included in output' -When { $False } { + + # Section and section content is not included in generated markdown + } +} + +# Generate markdown from the document definition +Invoke-PSDocument -Name 'Sample' -InputObject ''; +``` + +### Code + +You can use the Code statement to generate fenced code sections in markdown. An info string can optionally be specified using the `-Info` parameter. + +Syntax: + +```text +Code [-Info ] [-Body] +``` + +- `Info` - An info string that can be used to specify the language of the code block. + +Examples: + +```powershell +# A document definition named CodeBlock +Document 'CodeBlock' { + + # Define a code block that will be rendered as markdown instead of being executed + Code { + powershell.exe -Help + } +} + +# Generate markdown from the document definition +Invoke-PSDocument -Name 'CodeBlock' -InputObject $Null; +``` + +Generates a new `CodeBlock.md` document containing the `powershell.exe -Help` command line. + +```powershell +# A document definition named CodeBlockWithInfo +Document 'CodeBlockWithInfo' { + + # Define a code block that will be rendered in markdown as PowerShell + Code powershell { + Get-Item -Path .\; + } +} + +# Generate markdown from the document definition +Invoke-PSDocument -Name 'CodeBlockWithInfo' -InputObject $Null; +``` + +Generates a new `Test.md` document containing script code formatted with the powershell info string. + +```powershell +# A document definition named CodeBlockFromPipeline +Document 'CodeBlockFromPipeline' { + + # Execute Get-Help then create a code block from the output of the Get-Help command + Get-Help 'Invoke-PSDocument' | Code +} + +# Generate markdown from the document definition +Invoke-PSDocument -Name 'CodeBlockWithInfo' -InputObject $Null; +``` + +### Note + +Creates a block quote formatted as a DocFx Formatted Markdown note. + +Syntax: + +```text +Note [-Body] +``` + +Examples: + +```powershell +# A document definition named NoteBlock +Document 'NoteBlock' { + + # Define a note block + Note { + 'This is a note.' + } +} + +# Generate markdown from the document definition +Invoke-PSDocument -Name 'NoteBlock' -InputObject $Null; +``` + +Generates a new `NoteBlock.md` document containing a block quote formatted as a DFM note. + +### Warning + +Creates a block quote formatted as a DocFx Formatted Markdown warning. + +Syntax: + +```text +Warning [-Body] +``` + +Examples: + +```powershell +# A document definition named WarningBlock +Document 'WarningBlock' { + + Warning { + 'This is a warning.' + } +} + +# Generate markdown from the document definition +Invoke-PSDocument -Name 'WarningBlock' -InputObject $Null; +``` + +Generates a new `WarningBlock.md` document containing a block quote formatted as a DFM warning. + +### Table + +Creates a formatted table from pipeline objects. + +Syntax: + +```text +Table [-Property ] +``` + +- `-Property` - Filter the table to only the named columns. + +Examples: + +```powershell +# A document definition named Table +Document 'Table' { + + Section 'Directory list' { + + # Create a row for each child item of C:\ + Get-ChildItem -Path 'C:\' | Table -Property Name,PSIsContainer; + } +} + +# Generate markdown from the document definition +Invoke-PSDocument -Name 'Table'; +``` + +Generates a new `Table.md` document containing a table populated with a row for each item. Only the properties Name and PSIsContainer are added as columns. + +### Yaml + +Creates a yaml header. + +Syntax: + +```text +Yaml [-Body] +``` + +Examples: + +```powershell +# A document definition named YamlBlock +Document 'YamlBlock' { + + # Create a Yaml block of key value pairs + Yaml @{ + title = 'An example title' + } + + # Additional text to add to the document + 'Yaml header may not be rendered by some markdown viewers. See source to view yaml.' +} + +# Generate markdown from the document definition +Invoke-PSDocument -Name 'YamlBlock'; +``` + +Generates a new YamlBlock.md document containing a yaml header. An example of the output generated is available [here](/docs/examples/Yaml-header-output.md). + +## EXAMPLES + +```powershell + +Document 'Sample' { + + Section 'Introduction' { + 'This is a sample document that uses PSDocs keywords to construct a dynamic document.' + } + + Section 'Generated by' { + "This document was generated by $($Env:USERNAME)." + + $PSVersionTable | Table -Property Name,Value + } +} + +# Generate markdown from the document definition +Invoke-PSDocument -Name 'Sample'; +``` + +## NOTE + +An online version of this document is available at https://github.com/BernieWhite/PSDocs/blob/master/docs/keywords/PSDocs/en-US/about_PSDocs_Keywords.md. + +## SEE ALSO + +- [Invoke-PSDocument](Invoke-PSDocument.md) + +## KEYWORDS + +- Document +- Section +- Title +- Code +- Note +- Warning +- Table +- Yaml diff --git a/docs/keywords/Section.md b/docs/keywords/Section.md deleted file mode 100644 index 5314a29..0000000 --- a/docs/keywords/Section.md +++ /dev/null @@ -1,76 +0,0 @@ - -# Section - -## SYNOPSIS -Creates a new document section that contains content. - -## SYNTAX - -``` -Section [-Name] [-When ] -``` - -## EXAMPLES - -### EXAMPLE 1 - -```powershell -Document 'Test' { - - Section 'Directory list' { - Get-ChildItem -Path 'C:\' | Table -Property Name,PSIsContainer; - } -} - -Invoke-PSDocument -Name 'Test'; -``` - -Generates a new Test.md document containing a table listing all items directly within C:\. - -### EXAMPLE 2 - -```powershell -Document 'Test' { - - Section 'Directory list' -When { Test-Path -Path 'C:\' } { - Get-ChildItem -Path 'C:\' | Table -Property Name,PSIsContainer; - } -} - -Invoke-PSDocument -Name 'Test'; -``` - -Generates a new Test.md document containing a table listing all items directly within C:\, but only if C:\ exists. - -## PARAMETERS - -### -Name -The name of the section. - -```yaml -Type: String -Parameter Sets: (All) -Aliases: - -Required: True -Position: 1 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -When -An optional condition that must be met before the section is included. - -```yaml -Type: ScriptBlock -Parameter Sets: (All) -Aliases: - -Required: False -Position: None -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - diff --git a/docs/keywords/Table.md b/docs/keywords/Table.md deleted file mode 100644 index a97c217..0000000 --- a/docs/keywords/Table.md +++ /dev/null @@ -1,28 +0,0 @@ - -# Table - -## SYNOPSIS -Creates a formatted table. - -## SYNTAX - -``` -Table [-Property ] -``` - -## EXAMPLES - -### EXAMPLE 1 - -```powershell -Document 'Test' { - - Section 'Directory list' { - Get-ChildItem -Path 'C:\' | Table -Property Name,PSIsContainer; - } -} - -Invoke-PSDocument -Name 'Test'; -``` - -Generates a new Test.md document containing a table populated with a row for each item. Only the properties Name and PSIsContainer are added as columns. \ No newline at end of file diff --git a/docs/keywords/Warning.md b/docs/keywords/Warning.md deleted file mode 100644 index 06dfa95..0000000 --- a/docs/keywords/Warning.md +++ /dev/null @@ -1,46 +0,0 @@ - -# Warning - -## SYNOPSIS -Creates a formatted warning block. - -## SYNTAX - -``` -Warning [-Body] -``` - -## EXAMPLES - -### EXAMPLE 1 - -```powershell -Document 'Test' { - - Warning { - 'This is a warning.' - } -} - -Invoke-PSDocument -Name 'Test'; -``` - -Generates a new Test.md document containing a block quote formatted as a DFM warning. - - -## PARAMETERS - -### -Body -A block of inline text to insert. - -```yaml -Type: ScriptBlock -Parameter Sets: (All) -Aliases: - -Required: True -Position: 1 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` diff --git a/docs/keywords/Yaml.md b/docs/keywords/Yaml.md deleted file mode 100644 index ef72506..0000000 --- a/docs/keywords/Yaml.md +++ /dev/null @@ -1,46 +0,0 @@ - -# Yaml - -## SYNOPSIS -Creates a yaml header. - -## SYNTAX - -``` -Yaml [-Body] -``` - -## EXAMPLES - -### EXAMPLE 1 - -```powershell -Document 'Test' { - - Yaml @{ - title = 'An example title' - } -} - -Invoke-PSDocument -Name 'Test'; -``` - -Generates a new Test.md document containing a yaml header. - - -## PARAMETERS - -### -Body -A hashtable containing header key/values. - -```yaml -Type: Hashtable -Parameter Sets: (All) -Aliases: - -Required: True -Position: 1 -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` diff --git a/scripts/build-docs.ps1 b/scripts/build-docs.ps1 new file mode 100644 index 0000000..1aa2c11 --- /dev/null +++ b/scripts/build-docs.ps1 @@ -0,0 +1,37 @@ + +[CmdletBinding()] +param ( + [Switch]$Scaffold = $False +) + +if ($Scaffold) { + Import-Module '.\src\PSDocs' -Force; + Import-Module '.\src\PSDocs.Dsc' -Force; + + Update-MarkdownHelp -Path '.\docs\commands\PSDocs\en-US'; + Update-MarkdownHelp -Path '.\docs\commands\PSDocs.Dsc\en-US'; + + return; +} + +if (Test-Path -Path '.\build\docs') { + Remove-Item -Path '.\build\docs' -Recurse -Force; + + New-Item -Path '.\build\docs' -ItemType Directory -Force | Out-Null; +} + +# Generate external help files +New-ExternalHelp -OutputPath '.\build\docs\PSDocs' -Path '.\docs\commands\PSDocs\en-US','.\docs\keywords\PSDocs\en-US' -Force; +New-ExternalHelp -OutputPath '.\build\docs\PSDocs.Dsc' -Path '.\docs\commands\PSDocs.Dsc\en-US' -Force; + +# Clean up old external help files +Remove-Item -Path '.\src\PSDocs\**\*.help.txt'; +Remove-Item -Path '.\src\PSDocs\**\*-help.xml'; +Remove-Item -Path '.\src\PSDocs.Dsc\**\*.help.txt'; +Remove-Item -Path '.\src\PSDocs.Dsc\**\*-help.xml'; + +# Coyp new external help files +Copy-Item -Path '.\build\docs\PSDocs\*.*' -Destination '.\src\PSDocs\en-US'; +Copy-Item -Path '.\build\docs\PSDocs\*.*' -Destination '.\src\PSDocs\en-AU'; +Copy-Item -Path '.\build\docs\PSDocs.Dsc\*.*' -Destination '.\src\PSDocs.Dsc\en-US'; +Copy-Item -Path '.\build\docs\PSDocs.Dsc\*.*' -Destination '.\src\PSDocs.Dsc\en-AU'; \ No newline at end of file diff --git a/scripts/common.ps1 b/scripts/common.ps1 index 4b5ea08..d5bb40d 100644 --- a/scripts/common.ps1 +++ b/scripts/common.ps1 @@ -42,7 +42,10 @@ function RunTest { [String]$Path, [Parameter(Mandatory = $True)] - [String]$OutputPath + [String]$OutputPath, + + [Parameter(Mandatory = $False)] + [Switch]$CodeCoverage = $False ) begin { @@ -61,6 +64,10 @@ function RunTest { # Run Pester tests $pesterParams = @{ OutputFile = "$OutputPath\$TestGroup.xml"; OutputFormat = 'NUnitXml'; PesterOption = @{ IncludeVSCodeMarker = $True }; }; + if ($CodeCoverage) { + $pesterParams.Add('CodeCoverage', "$Path\..\src\$TestGroup\*.psm1"); + } + Invoke-Pester @pesterParams; } finally { diff --git a/scripts/test.ps1 b/scripts/test.ps1 index e97b1df..248e87b 100644 --- a/scripts/test.ps1 +++ b/scripts/test.ps1 @@ -9,7 +9,11 @@ param ( # Should output paths be cleaned first [Parameter(Mandatory = $False)] - [Switch]$Clean = $False + [Switch]$Clean = $False, + + # Code coverage should be calculated + [Parameter(Mandatory = $False)] + [Switch]$CodeCoverage = $False ) Write-Verbose -Message "[Test] BEGIN::"; @@ -47,9 +51,9 @@ if ($Null -eq $pesterModule) { } # Load Pester module -Import-Module -Name Pester -Verbose:$False; +Import-Module -Name Pester -RequiredVersion '3.4.0' -Verbose:$False; -@('PSDocs', 'PSDocs.Dsc') | RunTest -Path $testPath -OutputPath $reportsPath -Verbose:$VerbosePreference; +@('PSDocs', 'PSDocs.Dsc') | RunTest -Path $testPath -OutputPath $reportsPath -CodeCoverage:$CodeCoverage -Verbose:$VerbosePreference; # STEP : Publish results diff --git a/src/PSDocs.Dsc/PSDocs.Dsc.psd1 b/src/PSDocs.Dsc/PSDocs.Dsc.psd1 index f94c360..840be1b 100644 --- a/src/PSDocs.Dsc/PSDocs.Dsc.psd1 +++ b/src/PSDocs.Dsc/PSDocs.Dsc.psd1 @@ -8,7 +8,7 @@ RootModule = 'PSDocs.Dsc.psm1' # Version number of this module. -ModuleVersion = '0.2.0' +ModuleVersion = '0.3.0' # Supported PSEditions # CompatiblePSEditions = @() @@ -48,7 +48,7 @@ Description = 'Desired State Configuration (DSC) extensions for PSDocs.' # Modules that must be imported into the global environment prior to importing this module RequiredModules = @( - @{ ModuleName = 'PSDocs'; ModuleVersion = '0.2.0'; } + @{ ModuleName = 'PSDocs'; ModuleVersion = '0.3.0'; } ) # Assemblies that must be loaded prior to importing this module diff --git a/src/PSDocs.Dsc/PSDocs.Dsc.psm1 b/src/PSDocs.Dsc/PSDocs.Dsc.psm1 index 8f4fd25..5ed2baf 100644 --- a/src/PSDocs.Dsc/PSDocs.Dsc.psm1 +++ b/src/PSDocs.Dsc/PSDocs.Dsc.psm1 @@ -32,6 +32,7 @@ Import-LocalizedData -BindingVariable LocalizedData -FileName 'PSDocs.Dsc.Resour # Public functions # +# .ExternalHelp PSDocs.Dsc-Help.xml function Invoke-DscNodeDocument { [CmdletBinding()] @@ -70,6 +71,7 @@ function Invoke-DscNodeDocument { } } +# .ExternalHelp PSDocs.Dsc-Help.xml function Get-DscMofDocument { [CmdletBinding()] @@ -130,9 +132,7 @@ function BuildDocumentation { } } catch { - Write-Error -Message ($LocalizedData.ImportMofFailed -f $Path, $_.Exception.Message) -Exception $_.Exception; - - return; + Write-Error -Message ($LocalizedData.ImportMofFailed -f $Path, $_.Exception.Message) -Exception $_.Exception -ErrorAction Stop; } if ($PSBoundParameters.ContainsKey('Script')) { @@ -141,9 +141,7 @@ function BuildDocumentation { Import-PSDocumentTemplate -Path $Script -Verbose:$VerbosePreference; } catch { - Write-Error -Message ($LocalizedData.ImportDocumentTemplateFailed -f $Script, $_.Exception.Message) -Exception $_.Exception; - - return; + Write-Error -Message ($LocalizedData.ImportDocumentTemplateFailed -f $Script, $_.Exception.Message) -Exception $_.Exception -ErrorAction Stop; } } diff --git a/src/PSDocs/PSDocs.psd1 b/src/PSDocs/PSDocs.psd1 index 5b962ea..7752dcb 100644 --- a/src/PSDocs/PSDocs.psd1 +++ b/src/PSDocs/PSDocs.psd1 @@ -8,7 +8,7 @@ RootModule = 'PSDocs.psm1' # Version number of this module. -ModuleVersion = '0.2.0' +ModuleVersion = '0.3.0' # Supported PSEditions # CompatiblePSEditions = @() @@ -69,6 +69,7 @@ FunctionsToExport = @( 'Document' 'Invoke-PSDocument' 'Import-PSDocumentTemplate' + 'Get-PSDocumentHeader' ) # Cmdlets to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no cmdlets to export. diff --git a/src/PSDocs/PSDocs.psm1 b/src/PSDocs/PSDocs.psm1 index 5bdb288..6dbe550 100644 --- a/src/PSDocs/PSDocs.psm1 +++ b/src/PSDocs/PSDocs.psm1 @@ -16,7 +16,7 @@ Import-LocalizedData -BindingVariable LocalizedData -FileName 'PSDocs.Resources. # Public functions # -# Implement the document keyword +# .ExternalHelp PSDocs-Help.xml function Document { [CmdletBinding()] param ( @@ -42,6 +42,7 @@ function Document { } } +# .ExternalHelp PSDocs-Help.xml function Invoke-PSDocument { [CmdletBinding()] @@ -56,12 +57,12 @@ function Invoke-PSDocument { [Parameter(Mandatory = $False, ValueFromPipeline = $True)] [PSObject]$InputObject, - [Parameter(Mandatory = $False)] - [Object]$ConfigurationData, + # [Parameter(Mandatory = $False)] + # [Object]$ConfigurationData, # The path to look for document definitions in - [Parameter(Mandatory = $False)] - [String]$Path = $PWD, + # [Parameter(Mandatory = $False)] + # [String]$Path = $PWD, # The output path to save generated documentation [Parameter(Mandatory = $False)] @@ -86,6 +87,7 @@ function Invoke-PSDocument { } } +# .ExternalHelp PSDocs-Help.xml function Import-PSDocumentTemplate { [CmdletBinding()] @@ -101,6 +103,28 @@ function Import-PSDocumentTemplate { } } +# .ExternalHelp PSDocs-Help.xml +function Get-PSDocumentHeader { + + [CmdletBinding()] + param ( + [Parameter(Mandatory = $False, ValueFromPipelineByPropertyName = $True)] + [Alias('FullName')] + [String]$Path = $PWD + ) + + process { + + $filteredItems = Get-ChildItem -Path "$Path\*" -File; + + foreach ($item in $filteredItems) { + + ReadYamlHeader -Path $item.FullName -Verbose:$VerbosePreference; + } + + } +} + # # Internal language keywords # @@ -154,11 +178,20 @@ function Section { $Section = $result; - # Invoke the Section body and collect the results - $innerResult = $Body.Invoke(); + try { + # Invoke the Section body and collect the results + $innerResult = $Body.Invoke(); + + foreach ($r in $innerResult) { + $result.Node += $r; + } + } + catch { + + # Report non-terminating error + Write-Error -Message ($LocalizedData.SectionProcessFailure -f $_.Exception.Message) -Exception $_.Exception -ErrorId 'PSDocs.Section.ProcessFailure'; - foreach ($r in $innerResult) { - $result.Node += $r; + return; } # Emit Section object to the pipeline @@ -176,30 +209,51 @@ function Title { param ( [Parameter(Position = 0, Mandatory = $True)] [AllowEmptyString()] - [String]$Title + [String]$Content ) process { - $result = New-Object -TypeName PSObject -Property @{ Type = 'Title'; Content = $Title; }; - - $result; + # Update the document title + $Document.Title = $Content; } } function Code { [CmdletBinding()] param ( - [Parameter(Position = 0, Mandatory = $True)] - [ScriptBlock]$Body + # Body of the code block + [Parameter(Position = 0, Mandatory = $True, ParameterSetName = 'Default', ValueFromPipeline = $True)] + [Parameter(Position = 1, Mandatory = $True, ParameterSetName = 'InfoString', ValueFromPipeline = $True)] + [ScriptBlock]$Body, + + [Parameter(Mandatory = $True, ParameterSetName = 'StringDefault', ValueFromPipeline = $True)] + [Parameter(Mandatory = $True, ParameterSetName = 'StringInfoString', ValueFromPipeline = $True)] + [String]$BodyString, + + # Info-string + [Parameter(Position = 0, Mandatory = $True, ParameterSetName = 'InfoString')] + [Parameter(Position = 0, Mandatory = $True, ParameterSetName = 'StringInfoString')] + [String]$Info ) process { - $result = New-Object -TypeName PSObject -Property @{ Type = 'Code'; Content = ''; }; + $result = New-Object -TypeName PSObject -Property @{ Type = 'Code'; Info = ''; Content = ''; }; - $innerResult = $Body.InvokeWithContext($Null, $Null); + if (![String]::IsNullOrWhiteSpace($Info)) { + $result.Info = $Info.Trim(); + } - foreach ($r in $innerResult) { - $result.Content += $r; + if ($PSCmdlet.ParameterSetName -eq 'StringDefault' -or $PSCmdlet.ParameterSetName -eq 'StringInfoString') { + $result.Content = $BodyString; + } + else { + $result.Content = $Body.ToString(); + } + + # Cleanup indent + + if ($result.Content -match '^\r\n(? {1,})') { + $result.Content = $result.Content -replace "\r\n {1,$($Matches.indent.length)}", ''; } $result; @@ -277,14 +331,16 @@ function Yaml { [CmdletBinding()] param ( [Parameter(Position = 0, Mandatory = $True)] - [Hashtable]$Body + [System.Collections.IDictionary]$Body ) process { - $result = New-Object -TypeName PSObject -Property @{ Type = 'Yaml'; Node = @(); Content = $Body; }; - - $result; + # Process eaxch key value pair in the supplied dictionary/hashtable + foreach ($kv in $Body.GetEnumerator()) { + + $Document.Metadata[$kv.Key] = $kv.Value; + } } } @@ -292,7 +348,8 @@ function Table { [CmdletBinding()] param ( - [Parameter(Mandatory = $True, ValueFromPipeline = $True)] + [Parameter(Mandatory = $False, ValueFromPipeline = $True)] + [AllowNull()] [Object]$InputObject, [Parameter(Mandatory = $False, Position = 0)] @@ -443,8 +500,8 @@ function GenerateDocumentFn { [Parameter(Mandatory = $True, ValueFromPipeline = $True)] [PSObject]$InputObject, - [Parameter(Mandatory = $False)] - [Object]$ConfigurationData, + # [Parameter(Mandatory = $False)] + # [Object]$ConfigurationData, [Parameter(Mandatory = $False)] [String]$OutputPath = $PWD @@ -550,16 +607,26 @@ function GenerateDocument { Write-Verbose -Message "[Doc] -- Processing: $instance"; + $document = New-Object -TypeName PSObject -Property @{ Type = 'Document'; Metadata = ([Ordered]@{ }); Title = [String]::Empty; }; + # Define built-in variables [PSVariable[]]$variablesToDefine = @( New-Object -TypeName PSVariable -ArgumentList ('InstanceName', $instance) New-Object -TypeName PSVariable -ArgumentList ('InputObject', $InputObject) New-Object -TypeName PSVariable -ArgumentList ('Parameter', $parameter) New-Object -TypeName PSVariable -ArgumentList ('Section', $Section) - ); + New-Object -TypeName PSVariable -ArgumentList ('Document', $document) + ) - # Invoke the body of the document definition and get the output - $innerResult = $body.InvokeWithContext($functionsToDefine, $variablesToDefine); + try { + # Invoke the body of the document definition and get the output + $innerResult = $body.InvokeWithContext($functionsToDefine, $variablesToDefine); + } + catch { + Write-Error -Message $LocalizedData.DocumentProcessFailure -Exception $_.Exception -Category OperationStopped -ErrorId 'PSDocs.Document.ProcessFailure' -ErrorAction Stop; + } + + $innerResult.Insert(0, $document); # Create a document object model based on the output $dom = New-Object -TypeName PSObject -Property @{ Node = $innerResult; }; @@ -567,6 +634,13 @@ function GenerateDocument { # Build a path for the document $documentPath = Join-Path -Path $OutputPath -ChildPath "$instance.md"; + # Create parent path if it doesn't exist + $documentParent = Split-Path -Path $documentPath -Parent; + + if (!(Test-Path -Path $documentParent)) { + New-Item -Path $documentParent -ItemType Directory -Force | Out-Null; + } + # Parse the model ParseDom -Dom $dom -Processor (NewMarkdownProcessor) -Verbose:$VerbosePreference | WriteDocumentContent -Path $documentPath -PassThru:$PassThru; } @@ -813,6 +887,11 @@ function ReadYamlHeader { # Export module # -Export-ModuleMember -Function 'Document','Invoke-PSDocument','Import-PSDocumentTemplate'; +Export-ModuleMember -Function @( + 'Document' + 'Invoke-PSDocument' + 'Import-PSDocumentTemplate' + 'Get-PSDocumentHeader' +); # EOM \ No newline at end of file diff --git a/src/PSDocs/PSDocsProcessor/Markdown/Markdown.psm1 b/src/PSDocs/PSDocsProcessor/Markdown/Markdown.psm1 index 9eb2f4c..785615e 100644 --- a/src/PSDocs/PSDocsProcessor/Markdown/Markdown.psm1 +++ b/src/PSDocs/PSDocsProcessor/Markdown/Markdown.psm1 @@ -17,6 +17,7 @@ function Visit { } switch ($InputObject.Type) { + 'Document' { return VisitDocument($InputObject); } 'Code' { return VisitCode($InputObject); } 'Section' { return VisitSection($InputObject); } 'Title' { return VisitTitle($InputObject); } @@ -77,7 +78,16 @@ function VisitCode { Write-Verbose -Message "[Doc][Processor] -- Visit code"; - VisitString(" $($InputObject.Content)"); + if ([String]::IsNullOrEmpty($InputObject.Info)) { + VisitString('```'); + VisitString($InputObject.Content); + VisitString('```'); + } + else { + VisitString("``````$($InputObject.Info)"); + VisitString($InputObject.Content); + VisitString('```'); + } } function VisitTitle { @@ -85,7 +95,7 @@ function VisitTitle { Write-Verbose -Message "[Doc][Processor] -- Visit title"; - VisitString("# $($InputObject.Content)"); + VisitString("# $($InputObject.Title)"); } function VisitList { @@ -132,7 +142,7 @@ function VisitYaml { VisitString('---'); - foreach ($kv in $InputObject.Content.GetEnumerator()) { + foreach ($kv in $InputObject.Metadata.GetEnumerator()) { VisitString("$($kv.Key): $($kv.Value)"); } @@ -167,4 +177,19 @@ function VisitTable { } Write-Verbose -Message "[Doc][Processor][Table] END:: [$($table.Rows.Count)]"; +} + +function VisitDocument { + + param ( + $InputObject + ) + + if ($Null -ne $InputObject.Metadata -and $InputObject.Metadata.Count -gt 0) { + VisitYaml -InputObject $InputObject; + } + + if (![String]::IsNullOrEmpty($InputObject.Title)) { + VisitTitle -InputObject $InputObject; + } } \ No newline at end of file diff --git a/src/PSDocs/en-AU/PSDocs.Resources.psd1 b/src/PSDocs/en-AU/PSDocs.Resources.psd1 index 811338b..7037c67 100644 --- a/src/PSDocs/en-AU/PSDocs.Resources.psd1 +++ b/src/PSDocs/en-AU/PSDocs.Resources.psd1 @@ -2,5 +2,7 @@ ConvertFrom-StringData @' ###PSLOC DocumentNotFound=Failed to find document: {0} +DocumentProcessFailure=Failed to process document +SectionProcessFailure=Failed to process section: {0} ###PSLOC '@ \ No newline at end of file diff --git a/src/PSDocs/en-US/PSDocs.Resources.psd1 b/src/PSDocs/en-US/PSDocs.Resources.psd1 index 811338b..7037c67 100644 --- a/src/PSDocs/en-US/PSDocs.Resources.psd1 +++ b/src/PSDocs/en-US/PSDocs.Resources.psd1 @@ -2,5 +2,7 @@ ConvertFrom-StringData @' ###PSLOC DocumentNotFound=Failed to find document: {0} +DocumentProcessFailure=Failed to process document +SectionProcessFailure=Failed to process section: {0} ###PSLOC '@ \ No newline at end of file diff --git a/tests/PSDocs.Dsc.Tests/PSDocs.Dsc.Common.Tests.ps1 b/tests/PSDocs.Dsc.Tests/PSDocs.Dsc.Common.Tests.ps1 index 301a8c3..f172c84 100644 --- a/tests/PSDocs.Dsc.Tests/PSDocs.Dsc.Common.Tests.ps1 +++ b/tests/PSDocs.Dsc.Tests/PSDocs.Dsc.Common.Tests.ps1 @@ -9,7 +9,6 @@ param ( # Setup error handling $ErrorActionPreference = 'Stop'; -Set-StrictMode -Version latest; # Setup tests paths $rootPath = (Resolve-Path $PSScriptRoot\..\..).Path; @@ -19,6 +18,7 @@ $temp = "$here\..\..\build"; # $sut = (Split-Path -Leaf $MyInvocation.MyCommand.Path) -replace '\.Tests\.', '.'; Import-Module $src -Force; +Import-Module $src\..\PSDocs -Force; $outputPath = "$temp\PSDocs.Dsc.Tests\Common"; Remove-Item -Path $outputPath -Force -Recurse -Confirm:$False -ErrorAction SilentlyContinue; @@ -51,6 +51,26 @@ configuration TestConfiguration { } } +configuration TestConfiguration2 { + + param ( + [Parameter(Mandatory = $True)] + [String[]]$ComputerName + ) + + Import-DscResource -ModuleName PSDesiredStateConfiguration; + + node $ComputerName { + + File FileResource { + Ensure = 'Present' + Type = 'File' + DestinationPath = 'C:\environment.tag' + Contents = "Node=$($Node.NodeName)" + } + } + } + Describe 'PSDocs.Dsc' { Context 'Generate a document without an instance name' { @@ -145,4 +165,25 @@ Describe 'PSDocs.Dsc' { Get-Content -Path "$outputPath\WithExternalScript.md" -Raw | Should match '\|FS\-SMB1\|'; } } + + Context 'Generate a document with missing data' { + + # Define a test document with a table + document 'WithMissingData' { + + Section 'Windows features' { + + # Reference a resource type that is not included in the configuration + $InputObject.ResourceType.WindowsFeature | Table -Property Name,Ensure; + } + } + + TestConfiguration2 -OutputPath $outputPath -ComputerName 'WithMissingData'; + + Invoke-DscNodeDocument -DocumentName 'WithMissingData' -InstanceName 'WithMissingData' -Path $outputPath -OutputPath $outputPath; + + It 'Should output' { + Test-Path -Path "$outputPath\WithMissingData.md" | Should be $True; + } + } } diff --git a/tests/PSDocs.Tests/PSDocs.Code.Tests.ps1 b/tests/PSDocs.Tests/PSDocs.Code.Tests.ps1 index 4137d85..8929b41 100644 --- a/tests/PSDocs.Tests/PSDocs.Code.Tests.ps1 +++ b/tests/PSDocs.Tests/PSDocs.Code.Tests.ps1 @@ -35,7 +35,7 @@ Describe 'PSDocs -- Code keyword' { document 'CodeTests' { Code { - 'This is code' + This is code } } @@ -58,29 +58,71 @@ Describe 'PSDocs -- Code keyword' { } It 'Should have expected content' { - $Global:TestVars['VisitCode'].Content | Should be 'This is code'; + $Global:TestVars['VisitCode'].Content | Should match 'This is code'; } } Context 'Code markdown' { # Define a test document with a table - document 'CodeTests' { + document 'CodeMarkdown' { Code { - 'This is code' + This is code } } - $outputDoc = "$outputPath\Code.md"; - Invoke-PSDocument -Name 'CodeTests' -InstanceName 'Code' -InputObject $dummyObject -OutputPath $outputPath; + $outputDoc = "$outputPath\CodeMarkdown.md"; + Invoke-PSDocument -Name 'CodeMarkdown' -InputObject $dummyObject -OutputPath $outputPath; + + It 'Should have generated output' { + Test-Path -Path $outputDoc | Should be $True; + } + + It 'Should match expected format' { + Get-Content -Path $outputDoc -Raw | Should match 'This is code'; + } + } + + Context 'Code markdown with named format' { + + # Define a test document with a table + document 'CodeMarkdownNamedFormat' { + + Code powershell { + Get-Content + } + } + + $outputDoc = "$outputPath\CodeMarkdownNamedFormat.md"; + Invoke-PSDocument -Name 'CodeMarkdownNamedFormat' -InputObject $dummyObject -OutputPath $outputPath; + + It 'Should have generated output' { + Test-Path -Path $outputDoc | Should be $True; + } + + It 'Should match expected format' { + Get-Content -Path $outputDoc -Raw | Should match '```powershell\r\nGet-Content\r\n```'; + } + } + + Context 'Code markdown with evaluation' { + + # Define a test document with a table + document 'CodeMarkdownEval' { + + $a = 1; $a += 1; $a | Code powershell; + } + + $outputDoc = "$outputPath\CodeMarkdownEval.md"; + Invoke-PSDocument -Name 'CodeMarkdownEval' -InputObject $dummyObject -OutputPath $outputPath; It 'Should have generated output' { Test-Path -Path $outputDoc | Should be $True; } It 'Should match expected format' { - Get-Content -Path $outputDoc -Raw | Should match ' This is code'; + Get-Content -Path $outputDoc -Raw | Should match '```powershell\r\n2\r\n```'; } } } diff --git a/tests/PSDocs.Tests/PSDocs.Section.Tests.ps1 b/tests/PSDocs.Tests/PSDocs.Section.Tests.ps1 index f1b010b..a641939 100644 --- a/tests/PSDocs.Tests/PSDocs.Section.Tests.ps1 +++ b/tests/PSDocs.Tests/PSDocs.Section.Tests.ps1 @@ -85,4 +85,33 @@ Describe 'PSDocs -- Section keyword' { Get-Content -Path $outputDoc -Raw | Should match '## Test(\n|\r){1,2}Content'; } } + + Context 'Conditional section block' { + + # Define a test document with a section block + document 'SectionWhen' { + Section 'Section 1' -When { $False } { + 'Content 1' + } + + Section 'Section 2' -When { $True } { + 'Content 2' + } + } + + $outputDoc = "$outputPath\SectionWhen.md"; + Invoke-PSDocument -Name 'SectionWhen' -InputObject $dummyObject -OutputPath $outputPath; + + It 'Should have generated output' { + Test-Path -Path $outputDoc | Should be $True; + } + + It 'Should contain Section 2' { + Get-Content -Path $outputDoc -Raw | Should match '## Section 2\r\nContent 2'; + } + + It 'Should not contain Section 1' { + Get-Content -Path $outputDoc -Raw | Should not match '## Section 1\r\nContent 1'; + } + } } diff --git a/tests/PSDocs.Tests/PSDocs.Table.Tests.ps1 b/tests/PSDocs.Tests/PSDocs.Table.Tests.ps1 index 1384c81..dd98716 100644 --- a/tests/PSDocs.Tests/PSDocs.Table.Tests.ps1 +++ b/tests/PSDocs.Tests/PSDocs.Table.Tests.ps1 @@ -9,7 +9,6 @@ param ( # Setup error handling $ErrorActionPreference = 'Stop'; -Set-StrictMode -Version latest; # Setup tests paths $rootPath = (Resolve-Path $PSScriptRoot\..\..).Path; @@ -78,7 +77,7 @@ Describe 'PSDocs -- Table keyword' { Context 'Table single entry markdown' { - # Define a test document with a warning + # Define a test document with a table document 'TableSingleEntryMarkdown' { New-Object -TypeName PSObject -Property @{ Name = 'Single' } | Table -Property Name; @@ -95,4 +94,27 @@ Describe 'PSDocs -- Table keyword' { Get-Content -Path $outputDoc -Raw | Should match '\|Name\|\r\n\| --- \|\r\n\|Single\|'; } } + + Context 'Table with null' { + + # Define a test document with section and table + document 'TableWithNull' { + + Section 'Windows features' { + + $InputObject.ResourceType.WindowsFeature | Table -Property Name,Ensure; + } + } + + $outputDoc = "$outputPath\TableWithNull.md"; + Invoke-PSDocument -Name 'TableWithNull' -InputObject @{ ResourceType = @{ } } -OutputPath $outputPath; + + It 'Should have generated output' { + Test-Path -Path $outputDoc | Should be $True; + } + + It 'Should match expected format' { + Get-Content -Path $outputDoc -Raw | Should match '(## Windows features\r\n)$'; + } + } } diff --git a/tests/PSDocs.Tests/PSDocs.Title.Tests.ps1 b/tests/PSDocs.Tests/PSDocs.Title.Tests.ps1 new file mode 100644 index 0000000..b0ce041 --- /dev/null +++ b/tests/PSDocs.Tests/PSDocs.Title.Tests.ps1 @@ -0,0 +1,104 @@ +# +# Unit tests for the Title keyword +# + +[CmdletBinding()] +param ( + +) + +# Setup error handling +$ErrorActionPreference = 'Stop'; +Set-StrictMode -Version latest; + +# Setup tests paths +$rootPath = (Resolve-Path $PSScriptRoot\..\..).Path; +$here = Split-Path -Parent $MyInvocation.MyCommand.Path; +$src = ($here -replace '\\tests\\', '\\src\\') -replace '\.Tests', ''; +$temp = "$here\..\..\build"; +# $sut = (Split-Path -Leaf $MyInvocation.MyCommand.Path) -replace '\.Tests\.', '.'; + +Import-Module $src -Force; +Import-Module $src\PSDocsProcessor\Markdown -Force; + +$outputPath = "$temp\PSDocs.Tests\Title"; +New-Item $outputPath -ItemType Directory -Force | Out-Null; + +$dummyObject = New-Object -TypeName PSObject; + +$Global:TestVars = @{ }; + +Describe 'PSDocs -- Title keyword' { + Context 'Title' { + + # Define a test document with a title + document 'VisitTitle' { + + Title 'Test title' + } + + Mock -CommandName 'VisitTitle' -ModuleName 'Markdown' -Verifiable -MockWith { + param ( + $InputObject + ) + + $Global:TestVars['VisitTitle'] = $InputObject; + } + + Invoke-PSDocument -Name 'VisitTitle' -InstanceName 'VisitTitle' -InputObject $dummyObject -OutputPath $outputPath; + + It 'Should process Title keyword' { + Assert-MockCalled -CommandName 'VisitTitle' -ModuleName 'Markdown' -Times 1; + } + + It 'Should be Title object' { + $Global:TestVars['VisitTitle'].Type | Should be 'Document'; + } + + It 'Should have expected content' { + $Global:TestVars['VisitTitle'].Title | Should match 'Test title'; + } + } + + Context 'Single title markdown' { + + # Define a test document with a title + document 'SingleTitle' { + + Title 'Test title' + } + + $outputDoc = "$outputPath\SingleTitle.md"; + Invoke-PSDocument -Name 'SingleTitle' -InputObject $dummyObject -OutputPath $outputPath; + + It 'Should have generated output' { + Test-Path -Path $outputDoc | Should be $True; + } + + It 'Should match expected format' { + Get-Content -Path $outputDoc -Raw | Should match '^(\# Test title\r\n)'; + } + } + + Context 'Multiple title markdown' { + + # Define a test document with multiple titles + document 'MultipleTitle' { + + Title 'Title 1' + + Title 'Title 2' + } + + $outputDoc = "$outputPath\MultipleTitle.md"; + Invoke-PSDocument -Name 'MultipleTitle' -InputObject $dummyObject -OutputPath $outputPath; + + It 'Should have generated output' { + Test-Path -Path $outputDoc | Should be $True; + } + + It 'Should match expected format' { + Get-Content -Path $outputDoc -Raw | Should match '^(\# Title 2\r\n)'; + } + } +} diff --git a/tests/PSDocs.Tests/PSDocs.Warning.Tests.ps1 b/tests/PSDocs.Tests/PSDocs.Warning.Tests.ps1 index aa42d59..7b32342 100644 --- a/tests/PSDocs.Tests/PSDocs.Warning.Tests.ps1 +++ b/tests/PSDocs.Tests/PSDocs.Warning.Tests.ps1 @@ -49,11 +49,11 @@ Describe 'PSDocs -- Warning keyword' { Invoke-PSDocument -Name 'WarningVisitor' -InputObject $dummyObject -OutputPath $outputPath; - It 'Should process Note keyword' { + It 'Should process keyword' { Assert-MockCalled -CommandName 'VisitWarning' -ModuleName 'Markdown' -Times 1; } - It 'Should be Note object' { + It 'Should be expected type' { $Global:TestVars['VisitWarning'].Type | Should be 'Warning'; } diff --git a/tests/PSDocs.Tests/PSDocs.Yaml.Tests.ps1 b/tests/PSDocs.Tests/PSDocs.Yaml.Tests.ps1 new file mode 100644 index 0000000..1027b32 --- /dev/null +++ b/tests/PSDocs.Tests/PSDocs.Yaml.Tests.ps1 @@ -0,0 +1,171 @@ +# +# Unit tests for the Yaml keyword +# + +[CmdletBinding()] +param ( + +) + +# Setup error handling +$ErrorActionPreference = 'Stop'; +Set-StrictMode -Version latest; + +# Setup tests paths +$rootPath = (Resolve-Path $PSScriptRoot\..\..).Path; +$here = Split-Path -Parent $MyInvocation.MyCommand.Path; +$src = ($here -replace '\\tests\\', '\\src\\') -replace '\.Tests', ''; +$temp = "$here\..\..\build"; +# $sut = (Split-Path -Leaf $MyInvocation.MyCommand.Path) -replace '\.Tests\.', '.'; + +Import-Module $src -Force; +Import-Module $src\PSDocsProcessor\Markdown -Force; + +$outputPath = "$temp\PSDocs.Tests\Yaml"; +New-Item $outputPath -ItemType Directory -Force | Out-Null; + +$dummyObject = New-Object -TypeName PSObject; + +$Global:TestVars = @{ }; + +Describe 'PSDocs -- Yaml keyword' { + Context 'Yaml' { + + # Define a test document with a note + document 'YamlVisitor' { + + Yaml @{ + title = 'Test' + } + } + + Mock -CommandName 'VisitYaml' -ModuleName 'Markdown' -Verifiable -MockWith { + param ( + $InputObject + ) + + $Global:TestVars['VisitYaml'] = $InputObject; + } + + Invoke-PSDocument -Name 'YamlVisitor' -InputObject $dummyObject -OutputPath $outputPath; + + It 'Should process keyword' { + Assert-MockCalled -CommandName 'VisitYaml' -ModuleName 'Markdown' -Times 1; + } + + It 'Should be expected type' { + $Global:TestVars['VisitYaml'].Type | Should be 'Document'; + } + + It 'Should have expected content' { + $Global:TestVars['VisitYaml'].Metadata['title'] | Should be 'Test'; + } + } + + Context 'Yaml single entry' { + + # Define a test document with yaml content + document 'YamlSingleEntry' { + + Yaml ([ordered]@{ + title = 'Test' + }) + } + + $outputDoc = "$outputPath\YamlSingleEntry.md"; + Invoke-PSDocument -Name 'YamlSingleEntry' -InputObject $dummyObject -OutputPath $outputPath; + + It 'Should have generated output' { + Test-Path -Path $outputDoc | Should be $True; + } + + It 'Should match expected format' { + Get-Content -Path $outputDoc -Raw | Should match '---\r\ntitle: Test\r\n---'; + } + } + + Context 'Yaml multiple entries' { + + # Define a test document with yaml content + document 'YamlMultipleEntry' { + + Yaml ([ordered]@{ + value1 = 'ABC' + value2 = 'EFG' + }) + } + + $outputDoc = "$outputPath\YamlMultipleEntry.md"; + Invoke-PSDocument -Name 'YamlMultipleEntry' -InputObject $dummyObject -OutputPath $outputPath; + + It 'Should have generated output' { + Test-Path -Path $outputDoc | Should be $True; + } + + It 'Should match expected format' { + Get-Content -Path $outputDoc -Raw | Should match '---\r\nvalue1: ABC\r\nvalue2: EFG\r\n---'; + } + } + + Context 'Yaml multiple blocks' { + + # Define a test document with yaml content + document 'YamlMultipleBlock' { + + Yaml ([ordered]@{ + value1 = 'ABC' + }) + + Section 'Test' { + 'A test section spliting yaml blocks.' + } + + Yaml @{ + value2 = 'EFG' + } + } + + $outputDoc = "$outputPath\YamlMultipleBlock.md"; + Invoke-PSDocument -Name 'YamlMultipleBlock' -InputObject $dummyObject -OutputPath $outputPath; + + It 'Should have generated output' { + Test-Path -Path $outputDoc | Should be $True; + } + + It 'Should match expected format' { + Get-Content -Path $outputDoc -Raw | Should match '---\r\nvalue1: ABC\r\nvalue2: EFG\r\n---'; + } + } + + Context 'Document without Yaml block' { + + # Define a test document without yaml content + document 'NoYaml' { + + Section 'Test' { + 'A test section.' + } + } + + $outputDoc = "$outputPath\NoYaml.md"; + Invoke-PSDocument -Name 'NoYaml' -InputObject $dummyObject -OutputPath $outputPath; + + It 'Should have generated output' { + Test-Path -Path $outputDoc | Should be $True; + } + + It 'Should match expected format' { + Get-Content -Path $outputDoc -Raw | Should not match '---\r\n'; + } + } + + Context 'Get Yaml header' { + + $result = Get-PSDocumentHeader -Path $outputPath; + + It 'Should have data' { + $result | Should not be $Null; + } + + } +}