From 4502cc04f760e2d3725c966a1cab87973057c4a8 Mon Sep 17 00:00:00 2001 From: Aditya Patwardhan Date: Thu, 13 May 2021 08:17:53 -0700 Subject: [PATCH 01/27] Run Appveyor CI on branches other than v2 (#523) --- appveyor.yml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/appveyor.yml b/appveyor.yml index 3f444e08..870d373f 100644 --- a/appveyor.yml +++ b/appveyor.yml @@ -1,5 +1,9 @@ version: 0.11.0.{build} +branches: + except: + - v2 + install: - ps: | Write-Host "PowerShell Version:" $PSVersionTable.PSVersion.tostring() From 614b41956c6d32c24235723b21f423eeb3573e02 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Wed, 19 May 2021 14:46:40 -0500 Subject: [PATCH 02/27] Add v2.0 spec (#507) --- specs/platyps_2.0_update.md | 325 ++++++++++++++++++++++++++++++++++++ 1 file changed, 325 insertions(+) create mode 100644 specs/platyps_2.0_update.md diff --git a/specs/platyps_2.0_update.md b/specs/platyps_2.0_update.md new file mode 100644 index 00000000..11f2d53c --- /dev/null +++ b/specs/platyps_2.0_update.md @@ -0,0 +1,325 @@ +--- +RFC: RFCXXXX +Author: Jason Helmick +Status: Draft +Area: +Comments Due: +--- + +# PlatyPS 2.0 Update + +PlatyPS provides module owners with the ability to write PowerShell External Help in MarkDown. +PlatyPS generates downloadable and updatable help. + +## For this update + +PlatyPS expects Markdown to be authored in a particular way. We have defined a schema to determine +how parameters are described, where scripts examples are shown, and so on. The schema closely +resembles the existing output format of the `Get-Help` cmdlet in PowerShell. One of the primary +goals of this update is to improve the schema. The goal of 2.0.0 release is to maintain +compatibility while fixing the longstanding issues. + +This update includes the following goals: + +Priorities + +- Fix schema so that it contains all of the Help Data we need while maintaining as much + compatibility as possible with PS 5.1 and Exchange +- Switch markdown engine to markdig +- Fix OPS rendering problems (this may require specific changes in PlatyPS) + - Set up meeting with Robert after we have YAML conversion to the new schema so we can discuss + rendering requirements + +After the initial release, we should look at new features and consider whether we fork the tool to a +new no-legacy feature set or try to maintain compatibility going forward (ala PowerShellGet 3.0). + +## Motivation + +PowerShell external help files have been authored by hand or using complex tool chains and rendered +as MAML XML for use as console help. MAML is cumbersome to edit by hand, and common tools and +editors don't support it for complex scenarios like they do with Markdown. PlatyPS is provided as a +solution for allow documenting PowerShell help in any editor or tool that supports Markdown. + +An additional challenge PlatyPS tackles, is to handle PowerShell documentation for complex scenarios +(e.g. very large, closed source, and/or C#/binary modules) where it may be desirable to have +documentation abstracted away from the codebase. PlatyPS does not need source access to generate +documentation. + +Markdown is designed to be human-readable, without rendering. This makes writing and editing easy +and efficient. Many editors support it (Visual Studio Code, Sublime Text, etc), and many tools and +collaboration platforms (GitHub, Visual Studio Online) render the Markdown nicely. + +## Release plan + +- Proposed Preview + - TODO + +## Goals/Non-Goals + + Goals: + +- Update the Help file schema +- Update the About_ schema +- Update the cmdlet parameters to remove/add improvements +- TODO + +Non-goals: + +- TODO + +## Specification + +The proposal is to update the functionality and schema of PlayPS to improve the module owners +experience building and updating Help. + +### Help file schema + +The following sections outline schema changes for the Help file. + +| Heading | Level | Required? | Count | Description | +| ------------------ | ----- | --------- | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Title | H1 | Y | 1 | - Add reflection of cmdlet platform/alias based on platform
- Could do as Yaml block with Windows: macOS: Linux: (See block below table) | +| Synopsis | H2 | Y | 1 | - No changes | +| Syntax | H2 | Y | 1 | - No changes | +| Parameter Set Name | H3 | Y | 1-N | - Parameter Sets - should be sorted starting with Default, then by Alpha
- Parameters (in syntax block) - Should be sorted Positional, Required, then by Alpha | +| Description | H2 | Y | 1 | - Allow any content type
- No Headers H2, H3, H4 | +| Examples | H2 | Y | 1 | - No changes | +| Example | H3 | Y | 1-N | - Should require one code block at minimum per example
- Should not be restricted on elements or size | +| Parameters | H2 | Y | 1 | - Parameters Should be sorted Alpha. Currently PlatyPS has a switch to force Alpha versus enumerated. The default is off, please change to On. | +| Parameter | H3 | Y | 1-N | - Yaml block should include:
- Parameter Set Name
- AcceptedValues - Should display enumerated values of parameter (like ValidateSet)
- ConfirmImpact - Impact severity should be reflected and displayed to inform defaults for -Confirm | +| Common Parameters | H3 | Y | 1 | - Change the fwlink to remove local and version | +| Inputs | H2 | Y | 1 | - Add cross reference link to the API reference for the input/output object type
- [xref link docs](https://review.docs.microsoft.com/en-us/help/contribute/links-how-to?branch=master#xref-cross-reference-links) | +| Input type | H3 | N | 0-N | | +| Outputs | H2 | Y | 1 | - Add cross reference link to the API reference for the input/output object type
- [xref link docs](https://review.docs.microsoft.com/en-us/help/contribute/links-how-to?branch=master#xref-cross-reference-links) | +| Output type | H3 | N | 0-N | | +| Notes | H2 | N | 1 | Mandatory for schema but not rendered by OPS if empty | +| Related links | H3 | Y | 1 | - Link list should use bullets
- PlatyPS needs to support bullets
- Should support Text (prose), not just links | + +Structure of YAML for parameters + +```yaml +Type: System.String[] +Parameter Sets: PSetName1, PSetName2, PSetName3 +Aliases: + +Required: True (PSetName1, PSetName2) False (PSetName3) +Position: 0 +Default value: None +Accept pipeline input: True (ByPropertyName, ByValue) +Accept wildcard characters: True +DontShow: True +``` + +#### Schema feature requests + +1. Have a way to document aliases for the cmdlet. Today we only document aliases for parameters. + This is difficult to discover, so don't need `*-MarkdownHelp` cmdlets to create it but the schema + needs to support it. The author can add the information. For example: + + ```yaml + - aliases: + windows: gci, dir, ls + macOS: gci, dir + linux: gci, dir + ``` + +1. Have a some schema format for representing the availability of the cmdlet for a platform + (win/mac/linux). Could be one or more. Default to Windows but editable by the author. + + ```yaml + - platforms: win, macOS, linux + ``` + +### Formatting note + +- General + - Would like PlatyPS to add a line break after each Markdown block + - Example - Headers, Code blocks, Lists + - Bug: `Get-Help`: Requires that the first line of text be immediately following Synopsis header + +### About_ file schema + +The following sections outline schema changes for the About_ file. + +| Heading | Level | Required? | Count | Description | +| ----------------- | ----- | --------- | ----- | ------------------------------------------------------------------------------------------------------------------------- | +| Title | H1 | Y | 1 | - Title should be Sentence Case - About Topic
- Title meta data 'about_' should match the file basename | +| Short Description | H2 | Y | 1 | - Should be Sentence Case | +| Long Description | H2 | Y | 1 | - Should be Sentence case
- Should allow multiple Long description subtopics
- Should support subtopics at H3 or H2 | +| See Also | H2 | Y | 1 | - This is required but may be empty | + +General notes + +- Should be rendered as plain text compatible with `Get-Help` +- `Get-Help` bug:Synopsis +- [Get-Help bug](https://github.com/PowerShell/PowerShell/issues/9208) +- Add switch to provide Cabs or Zips. Default: cabs +- Add switch to include markdown Default: off +- About_ schema does not say anything about line wrapping etc. + - If left as text files, then wrap at 80 columns. + - But if converted to schema-based line limit is not a problem (for the future). Still a problem + for previous versions. + +## PlatyPS Cmdlets and Parameters + +PlatyPS includes a set of cmdlets with parameters. + +The following section is a review of the cmdlets for changes to the parameters and their defaults. +We need to decide to what cmdlets and features to keep. We should make a list breaking changes for +documentation. + +In case of breaking changes, do we need a legacy mode? + +- We don't know until we see what all the breaking changes are +- If we make changes that require changes to Get-Help we will need something that targets a older + versions PowerShell. + +#### Get-HelpPreview + +| ParamName | DefaultValue | Description | +| ---------------------- | ------------ | ------------------------------------------------------------------------------------------ | +| Path | None | Specifies an array of paths of MAML external help files | +| ConvertNotesToList | False | Indicates that this cmldet formats multiple paragraph items in the NOTES section as single | +| ConvertDoubleDashLists | False | Indicates that this cmldet converts double-hyphen list bullets into single-hyphen bullets | + +#### Get-MarkdownMetadata + +| ParamName | DefaultValue | Description | +| --------- | ------------ | -------------------------------------------------------- | +| Path | None | Specifies an array of paths of markdown files or folders | +| Markdown | None | Specifies a string that contains markdown formatted text | + +#### Merge-MarkdownHelp + +| ParamName | DefaultValue | Description | +| ----------------------- | ---------------- | ------------------------------------------------------------------------------------- | +| Encoding | UTF8 without BOM | Specifies the character encoding for your external help file. Specify a System.Text.E | +| ExplicitApplicableIfAll | False | Always write out full list of applicable tags. By default cmdlets and parameters that | +| Force | False | Indicates that this cmdlet overwrites an existing file that has the same name | +| MergeMarker | '!!! ' | String to be used as a merge text indicator. Applicable tag list would be included | +| OutputPath | None | Specifies the path of the folder where this cmdlet creates the combined markdown help | +| Path | None | Specifies an array of paths of markdown files or folders. This cmdlet creates | + +#### New-ExternalHelp + +| ParamName | DefaultValue | Description | +| ------------- | ---------------- | ----------------------------------------------------------------------------------------------- | +| OutputPath | None | Specifies the path of a folder where this cmdlet saves your external help file. The folder name | +| Encoding | UTF8 without BOM | Specifies the character encoding for your external help file. Specify a System.Text.Encoding | +| Force | False | Indicates that this cmdlet overwrites an existing file that has the same name | +| Path | None | Specifies an array of paths of markdown files or folders. This cmdlet creates external help | +| ApplicableTag | None | Specify array of tags to use as a filter. If cmdlet has `applicable` in the yaml metadata | +| MaxAboutWidth | 80 | Specifies the maximimum line length when generating "about" help text files. | +| ErrorLogFile | None | The path where this cmdlet will save formatted results log file | +| ShowProgress | False | Display progress bars under parsing existing markdown files | + +#### New-ExternalHelpCab + +| ParamName | DefaultValue | Description | +| -------------------- | ------------ | ------------------------------------------------------------------------------------------- | +| CabFilesFolder | None | Specifies the folder that contains the help content that this cmdlet packages into a .cab | +| LandingPagePath | None | Specifies the full path of the Module Markdown file that contains all the metadata required | +| OutputFolder | None | Specifies the location of the .cab file and helpinfo.xml file that this cmdlet creates | +| IncrementHelpVersion | False | Automatically increment the help version in the module markdown file | + +#### New-MarkdownAboutHelp + +| ParamName | DefaultValue | Description | +| ------------ | ------------ | ------------------------------------------ | +| AboutName | None | The name of the about topic | +| OutputFolder | None | The directory to create the about topic in | + +#### New-MarkdownHelp + +| ParamName | DefaultValue | Description | +| ---------------------- | ---------------- | --------------------------------------------------------------------------------------- | +| Command | None | Specifies the name of a command in your current session. This can be any command | +| Encoding | UTF8 without BOM | Specifies the character encoding for your markdown help files | +| Force | False | Indicates that this cmdlet overwrites existing files that have the same names | +| FwLink | None | Specifies the forward link for the module page. This value is required for .cab | +| HelpVersion | None | Specifies the version of your help. This value is required for .cab file creation | +| Locale | None | Specifies the locale of your help. This value is required for .cab file creation | +| MamlFile | None | Specifies an array of paths path of MAML .xml help files | +| Metadata | None | Specifies metadata that this cmdlet includes in the help markdown files as a hash table | +| Module | None | Specifies an array of names of modules for which this cmdlet creates help in markdown | +| ModuleGuid | None | Specifies the GUID of the module of your help. This value is required for .cab file | +| ModuleName | None | Specifies the name of the module of your help. This value is required for .cab file | +| NoMetadata | False | Indicates that this cmdlet does not write any metadata in the generated markdown | +| OnlineVersionUrl | None | Specifies the URL where the updatable help function downloads updated help | +| OutputFolder | None | Specifies the path of the folder where this cmdlet creates the markdown help files | +| WithModulePage | False | Indicates that this cmdlet creates a module page in the output folder | +| ConvertNotesToList | False | Indicates that this cmldet formats multiple paragraph items in the NOTES section | +| ConvertDoubleDashLists | False | Indicates that this cmldet converts double-hyphen list bullets into single-hyphen | +| AlphabeticParamsOrder | False | Order parameters alphabetically by name in PARAMETERS section. There are 5 exceptions | +| UseFullTypeName | False | Indicates that the target document will use a full type name instead of a short name | +| Session | None | Provides support for remote commands. Pass the session that you used to create | +| ModulePagePath | None | When WithModule parameter is used by default it puts .md file in same location as all | +| ExcludeDontShow | False | Exclude the parameters marked with `DontShow` in the parameter attribute from the help | + +#### New-YamlHelp + +| ParamName | DefaultValue | Description | +| ------------ | ------------ | --------------------------------------------------------------------------------------------------- | +| Encoding | None | Specifies the character encoding for your external help file. Specify a System.Text.Encoding object | +| Force | False | Indicates that this cmdlet overwrites an existing file that has the same name | +| Path | None | Specifies an array of paths of markdown files or folders | +| OutputFolder | None | Specifies the folder to create the YAML files | + +#### Update-MarkdownHelp + +| ParamName | DefaultValue | Description | +| --------------------- | ---------------- | ------------------------------------------------------------------------------------ | +| Encoding | UTF8 without BOM | Specifies the character encoding for your markdown help files | +| LogAppend | False | Indicates that this cmdlet appends information to the log instead overwriting it | +| LogPath | None | Specifies a file path for log information. The cmdlet writes the VERBOSE stream | +| Path | None | Specifies an array of paths of markdown files and folders to update | +| AlphabeticParamsOrder | False | Order parameters alphabetically by name in PARAMETERS section | +| UseFullTypeName | False | Indicates that the target document will use a full type name instead of a short name | +| Session | None | Provides support for remote commands. Pass the session that you used to create | +| UpdateInputOutput | False | Refreshes the Input and Output section to reflect the current state of the cmdlet | +| Force | False | Remove help files that no longer exists within sessions | +| ExcludeDontShow | False | Exclude the parameters marked with `DontShow` in the parameter attribute | + +#### Update-MarkdownHelpModule + +| ParamName | DefaultValue | Description | +| --------------------- | ---------------- | -------------------------------------------------------------------------------------- | +| Encoding | UTF8 without BOM | Specifies the character encoding for your markdown help files | +| LogAppend | False | Indicates that this cmdlet appends information to the log instead overwriting | +| LogPath | None | Specifies a file path for log information. The cmdlet writes the VERBOSE stream | +| Path | None | Specifies an array of paths of markdown folders to update. The folder must contain | +| RefreshModulePage | False | Update module page when updating the help module | +| AlphabeticParamsOrder | False | Order parameters alphabetically by name in PARAMETERS section | +| Session | None | Provides support for remote commands. Pass the session that you used to create | +| UseFullTypeName | False | Indicates that the target document will use a full type name instead of a short name | +| UpdateInputOutput | False | Refreshes the Input and Output sections to reflect the current state of the cmdlet | +| ModulePagePath | None | When -RefreshModulePage is used by default it puts .md file in same location | +| Force | False | Remove help files that no longer exists within sessions | +| ExcludeDontShow | False | Exclude the parameters marked with `DontShow` in the parameter attribute from the help | + +## Cmdlet Feature requests + +1. I was wondering if we should default to zips instead, one package for both platforms. Cabs as + legacy for < 5.1 content. We can fix PS 7.2 to look for zip first and fallback to cab. Add as + question in spec — This should be a switch - cab, zip or both. + +1. Need to know about Merge-MarkdownHelp which uses `applicable:` yaml syntax for version. + `applicable:` should be mentioned in the schema. — this creates tags…for linux/windows + parameters. Exchange uses the `applicable:` feature heavily. Need to maintain support for them. + +1. Need way to increment the help version number of the CAB files + + - Could be automatic in every build? + - Could be scheduled? + - Could be a workflow step (scripted) done by the author + - Need to figure out limits of version number fields + - Need rules for when to increment major, minor, subminor, etc. (Semvar?) + +### List of things that break with PS5.1 or Exchange + +TODO + +## Issues for this milestone + +[2.0-consider](https://github.com/PowerShell/platyPS/issues?q=is%3Aopen+is%3Aissue+milestone%3A2.0-consider) + From 7da47510f5b3fd7ac20baaed4a8b2e4bc0fea5ee Mon Sep 17 00:00:00 2001 From: Aditya Patwardhan Date: Tue, 29 Jun 2021 16:40:13 -0700 Subject: [PATCH 03/27] Fix issues with module name and external help file metadata (#542) --- .../Model/YAML/YamlInputOutput.cs | 18 ++- src/platyPS/platyPS.psm1 | 51 +++++- test/Pester/PlatyPs.Tests.ps1 | 25 +++ .../assets/ModuleWithDash/Test-Module.md | 16 ++ .../ModuleWithDash/Test-ModuleCmdlet.md | 46 ++++++ test/Pester/assets/NestedMod/Nest.psm1 | 7 + test/Pester/assets/NestedMod/NestedMod.psd1 | 132 +++++++++++++++ test/Pester/assets/New-YamlHelp.md | 153 ++++++++++++++++++ 8 files changed, 444 insertions(+), 4 deletions(-) create mode 100644 test/Pester/assets/ModuleWithDash/Test-Module.md create mode 100644 test/Pester/assets/ModuleWithDash/Test-ModuleCmdlet.md create mode 100644 test/Pester/assets/NestedMod/Nest.psm1 create mode 100644 test/Pester/assets/NestedMod/NestedMod.psd1 create mode 100644 test/Pester/assets/New-YamlHelp.md diff --git a/src/Markdown.MAML/Model/YAML/YamlInputOutput.cs b/src/Markdown.MAML/Model/YAML/YamlInputOutput.cs index 1c678ebd..6c8625e5 100644 --- a/src/Markdown.MAML/Model/YAML/YamlInputOutput.cs +++ b/src/Markdown.MAML/Model/YAML/YamlInputOutput.cs @@ -2,7 +2,23 @@ { public class YamlInputOutput { - public string Type { get; set; } + string _type; + public string Type + { + get + { + if (_type.Contains("#")) + { + return _type.Replace("#", "\\#"); + } + + return _type; + } + set + { + _type = value; + } + } public string Description { get; set; } } } \ No newline at end of file diff --git a/src/platyPS/platyPS.psm1 b/src/platyPS/platyPS.psm1 index 763023db..26810ac4 100644 --- a/src/platyPS/platyPS.psm1 +++ b/src/platyPS/platyPS.psm1 @@ -834,7 +834,12 @@ function New-ExternalHelp process { - $MarkdownFiles += GetMarkdownFilesFromPath $Path + $files = GetMarkdownFilesFromPath $Path + + if ($files) + { + $MarkdownFiles += FilterMdFileToExcludeModulePage -Path $files + } if($MarkdownFiles) { @@ -1481,6 +1486,35 @@ function GetAboutTopicsFromPath return $AboutMarkDownFiles } +function FilterMdFileToExcludeModulePage { + [CmdletBinding()] + param( + [Parameter(Mandatory = $true)] + [System.IO.FileInfo[]]$Path + ) + + $MarkdownFiles = @() + + if ($Path) { + $Path | ForEach-Object { + if (Test-Path $_.FullName) { + $md = Get-Content -Raw -Path $_.FullName + $yml = [Markdown.MAML.Parser.MarkdownParser]::GetYamlMetadata($md) + $isModulePage = $null -ne $yml.'Module Guid' + + if (-not $isModulePage) { + $MarkdownFiles += $_ + } + } + else { + Write-Error -Message ($LocalizedData.PathNotFound -f $_.FullName) + } + } + } + + return $MarkdownFiles +} + function GetMarkdownFilesFromPath { [CmdletBinding()] @@ -1503,7 +1537,6 @@ function GetMarkdownFilesFromPath $aboutFilePrefixPattern = 'about_*' - $MarkdownFiles = @() if ($Path) { $Path | ForEach-Object { @@ -1830,6 +1863,13 @@ function GetHelpFileName Where-Object {$_.ModuleType -ne 'Manifest'} | Where-Object {$_.ExportedCommands.Keys -contains $CommandInfo.Name} + $nestedModules = @( + ($CommandInfo.Module.NestedModules) | + Where-Object { $_.ModuleType -ne 'Manifest' } | + Where-Object { $_.ExportedCommands.Keys -contains $CommandInfo.Name } | + Select-Object -ExpandProperty Path + ) + if (-not $module) { Write-Warning -Message ($LocalizedData.ModuleNotFoundFromCommand -f '[GetHelpFileName]', $CommandInfo.Name) @@ -1846,7 +1886,12 @@ function GetHelpFileName { # for regular modules, we can deduct the filename from the module path file $moduleItem = Get-Item -Path $module.Path - if ($moduleItem.Extension -eq '.psm1') { + + $isModuleItemNestedModule = + $null -ne ($nestedModules | Where-Object { $_ -eq $module.Path }) -and + $CommandInfo.ModuleName -ne $module.Name + + if ($moduleItem.Extension -eq '.psm1' -and -not $isModuleItemNestedModule) { $fileName = $moduleItem.BaseName } else { $fileName = $moduleItem.Name diff --git a/test/Pester/PlatyPs.Tests.ps1 b/test/Pester/PlatyPs.Tests.ps1 index 153604d0..c5780914 100644 --- a/test/Pester/PlatyPs.Tests.ps1 +++ b/test/Pester/PlatyPs.Tests.ps1 @@ -705,6 +705,18 @@ Get-Alpha [-WhatIf] [[-CCC] ] [[-ddd] ] [] $help.parameters.parameter | Where-Object { $_.Name -eq 'NameNoWildCard' } | ForEach-Object { $_.globbing -eq 'false'} } } + + Context 'External help file metadata' { + BeforeAll { + Import-Module "$PSScriptRoot/assets/NestedMod" -Force + $nestedMd = New-MarkdownHelp -Module "NestedMod" -OutputFolder "$TestDrive\NestedMod" + } + + It 'checks the external help file metadata is correct for nested module' { + $m = Get-MarkdownMetadata -Path $nestedMd + $m['external help file'] | Should -BeExactly 'Nest.psm1-help.xml' + } + } } } @@ -723,6 +735,8 @@ Describe 'New-ExternalHelp' { } $file = New-MarkdownHelp -Command 'Test-OrderFunction' -OutputFolder $TestDrive -Force $maml = $file | New-ExternalHelp -OutputPath "$TestDrive\TestOrderFunction.xml" -Force + + $extHelp = New-ExternalHelp -Path "$PSScriptRoot/assets/ModuleWithDash" -OutputPath "$TestDrive\ModuleWithDash" } It "generates right order for syntax" { @@ -739,6 +753,10 @@ Describe 'New-ExternalHelp' { $xml = [xml] (Get-Content (Join-Path $TestDrive 'TestOrderFunction.xml')) $xml.helpItems.namespaceuri | Should Be 'http://msh' } + + It 'checks that external help can be generated for modules with dash in it' { + $extHelp | Should -Exist + } } Describe 'New-ExternalHelp -ErrorLogFile' { @@ -1612,4 +1630,11 @@ Describe 'New-YamlHelp' { It 'throws for OutputFolder that is a file'{ { New-YamlHelp "$root\docs\New-YamlHelp.md" -OutputFolder "$outFolder\yaml\New-YamlHelp.yml" } | Should Throw } + + It 'does not omit # in output type names' { + + $ymlFile = New-YamlHelp "$PSScriptRoot\assets\New-YamlHelp.md" -OutputFolder "$TestDrive\yaml" -Force + + Get-Content $ymlFile | Should -Contain '- type: IResult\#System.IO.FileInfo[]' + } } diff --git a/test/Pester/assets/ModuleWithDash/Test-Module.md b/test/Pester/assets/ModuleWithDash/Test-Module.md new file mode 100644 index 00000000..95810fd9 --- /dev/null +++ b/test/Pester/assets/ModuleWithDash/Test-Module.md @@ -0,0 +1,16 @@ +--- +Module Name: Test-Module +Module Guid: ad057547-0b77-49d0-b8dd-9ffd6d44b0be +Download Help Link: {{ Update Download Link }} +Help Version: {{ Please enter version of help manually (X.X.X.X) format }} +Locale: en-US +--- + +# Test-Module Module +## Description +{{ Fill in the Description }} + +## Test-Module Cmdlets +### [Test-ModuleCmdlet](Test-ModuleCmdlet.md) +{{ Fill in the Description }} + diff --git a/test/Pester/assets/ModuleWithDash/Test-ModuleCmdlet.md b/test/Pester/assets/ModuleWithDash/Test-ModuleCmdlet.md new file mode 100644 index 00000000..be9093db --- /dev/null +++ b/test/Pester/assets/ModuleWithDash/Test-ModuleCmdlet.md @@ -0,0 +1,46 @@ +--- +external help file: Test-Module-help.xml +Module Name: Test-Module +online version: +schema: 2.0.0 +title: Test-ModuleCmdlet +--- + +# Test-ModuleCmdlet + +## SYNOPSIS +{{ Fill in the Synopsis }} + +## SYNTAX + +``` +Test-ModuleCmdlet [] +``` + +## DESCRIPTION +{{ Fill in the Description }} + +## EXAMPLES + +### Example 1 +```powershell +PS C:\> {{ Add example code here }} +``` + +{{ Add example description here }} + +## PARAMETERS + +### 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/test/Pester/assets/NestedMod/Nest.psm1 b/test/Pester/assets/NestedMod/Nest.psm1 new file mode 100644 index 00000000..4d31bb9a --- /dev/null +++ b/test/Pester/assets/NestedMod/Nest.psm1 @@ -0,0 +1,7 @@ +function Get-Nest +{ + [CmdletBinding()] + param( + [Parameter()] [string] $str + ) +} \ No newline at end of file diff --git a/test/Pester/assets/NestedMod/NestedMod.psd1 b/test/Pester/assets/NestedMod/NestedMod.psd1 new file mode 100644 index 00000000..dcd2fbfb --- /dev/null +++ b/test/Pester/assets/NestedMod/NestedMod.psd1 @@ -0,0 +1,132 @@ +# +# Module manifest for module 'NestedMod' +# +# Generated by: adity +# +# Generated on: 6/28/2021 +# + +@{ + +# Script module or binary module file associated with this manifest. +# RootModule = '' + +# Version number of this module. +ModuleVersion = '0.0.1' + +# Supported PSEditions +# CompatiblePSEditions = @() + +# ID used to uniquely identify this module +GUID = '5aeb9dc7-b9f0-4bf2-8eb5-13663c1bd458' + +# Author of this module +Author = 'adity' + +# Company or vendor of this module +CompanyName = 'Unknown' + +# Copyright statement for this module +Copyright = '(c) adity. All rights reserved.' + +# Description of the functionality provided by this module +# Description = '' + +# Minimum version of the PowerShell engine required by this module +# PowerShellVersion = '' + +# Name of the PowerShell host required by this module +# PowerShellHostName = '' + +# Minimum version of the PowerShell host required by this module +# PowerShellHostVersion = '' + +# Minimum version of Microsoft .NET Framework required by this module. This prerequisite is valid for the PowerShell Desktop edition only. +# DotNetFrameworkVersion = '' + +# Minimum version of the common language runtime (CLR) required by this module. This prerequisite is valid for the PowerShell Desktop edition only. +# ClrVersion = '' + +# Processor architecture (None, X86, Amd64) required by this module +# ProcessorArchitecture = '' + +# Modules that must be imported into the global environment prior to importing this module +# RequiredModules = @() + +# Assemblies that must be loaded prior to importing this module +# RequiredAssemblies = @() + +# Script files (.ps1) that are run in the caller's environment prior to importing this module. +# ScriptsToProcess = @() + +# Type files (.ps1xml) to be loaded when importing this module +# TypesToProcess = @() + +# Format files (.ps1xml) to be loaded when importing this module +# FormatsToProcess = @() + +# Modules to import as nested modules of the module specified in RootModule/ModuleToProcess +NestedModules = @('Nest.psm1') + +# Functions 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 functions to export. +FunctionsToExport = 'Get-Nest' + +# 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. +CmdletsToExport = '*' + +# Variables to export from this module +VariablesToExport = '*' + +# Aliases 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 aliases to export. +AliasesToExport = '*' + +# DSC resources to export from this module +# DscResourcesToExport = @() + +# List of all modules packaged with this module +# ModuleList = @() + +# List of all files packaged with this module +# FileList = @() + +# Private data to pass to the module specified in RootModule/ModuleToProcess. This may also contain a PSData hashtable with additional module metadata used by PowerShell. +PrivateData = @{ + + PSData = @{ + + # Tags applied to this module. These help with module discovery in online galleries. + # Tags = @() + + # A URL to the license for this module. + # LicenseUri = '' + + # A URL to the main website for this project. + # ProjectUri = '' + + # A URL to an icon representing this module. + # IconUri = '' + + # ReleaseNotes of this module + # ReleaseNotes = '' + + # Prerelease string of this module + # Prerelease = '' + + # Flag to indicate whether the module requires explicit user acceptance for install/update/save + # RequireLicenseAcceptance = $false + + # External dependent modules of this module + # ExternalModuleDependencies = @() + + } # End of PSData hashtable + +} # End of PrivateData hashtable + +# HelpInfo URI of this module +# HelpInfoURI = '' + +# Default prefix for commands exported from this module. Override the default prefix using Import-Module -Prefix. +# DefaultCommandPrefix = '' + +} + diff --git a/test/Pester/assets/New-YamlHelp.md b/test/Pester/assets/New-YamlHelp.md new file mode 100644 index 00000000..b64e0c8d --- /dev/null +++ b/test/Pester/assets/New-YamlHelp.md @@ -0,0 +1,153 @@ +--- +external help file: platyPS-help.xml +Module Name: platyPS +online version: https://github.com/PowerShell/platyPS/blob/master/docs/New-YamlHelp.md +schema: 2.0.0 +--- + +# New-YamlHelp + +## SYNOPSIS +Converts Markdown help into YAML to be read easily by external tools + +## SYNTAX + +``` +New-YamlHelp [-Path] -OutputFolder [-Encoding ] [-Force] [] +``` + +## DESCRIPTION +The **New-YamlHelp** cmdlet works similarly to the **New-ExternalHelp** cmdlet but rather than creating a MAML file to support **Get-Help**, it creates a set of YAML files that can be read by external tools to provide custom rendering of help pages. + +## EXAMPLES + +### Example 1: Create YAML files +``` +PS C:\> New-YamlHelp -Path .\docs -OutputFolder .\out\yaml + + Directory: D:\Working\PlatyPS\out\yaml + + +Mode LastWriteTime Length Name +---- ------------- ------ ---- +-a---- 6/15/2017 11:13 AM 2337 Get-HelpPreview.yml +-a---- 6/15/2017 11:13 AM 3502 Get-MarkdownMetadata.yml +-a---- 6/15/2017 11:13 AM 4143 New-ExternalHelp.yml +-a---- 6/15/2017 11:13 AM 3082 New-ExternalHelpCab.yml +-a---- 6/15/2017 11:13 AM 2581 New-MarkdownAboutHelp.yml +-a---- 6/15/2017 11:13 AM 12356 New-MarkdownHelp.yml +-a---- 6/15/2017 11:13 AM 1681 New-YamlHelp.yml +-a---- 6/15/2017 11:13 AM 5053 Update-MarkdownHelp.yml +-a---- 6/15/2017 11:13 AM 4661 Update-MarkdownHelpModule.yml +-a---- 6/15/2017 11:13 AM 3350 Update-MarkdownHelpSchema.yml +``` + +This creates one YAML file for each cmdlet so external tools can read the structured data for each cmdlet. + +### Example 2: Create YAML files with specific encoding +``` +PS C:\> New-YamlHelp -Path .\docs -OutputFolder .\out\yaml -Force -Encoding ([System.Text.Encoding]::Unicode) + + Directory: D:\Working\PlatyPS\out\yaml + + +Mode LastWriteTime Length Name +---- ------------- ------ ---- +-a---- 6/15/2017 11:13 AM 2337 Get-HelpPreview.yml +-a---- 6/15/2017 11:13 AM 3502 Get-MarkdownMetadata.yml +-a---- 6/15/2017 11:13 AM 4143 New-ExternalHelp.yml +-a---- 6/15/2017 11:13 AM 3082 New-ExternalHelpCab.yml +-a---- 6/15/2017 11:13 AM 2581 New-MarkdownAboutHelp.yml +-a---- 6/15/2017 11:13 AM 12356 New-MarkdownHelp.yml +-a---- 6/15/2017 11:13 AM 1681 New-YamlHelp.yml +-a---- 6/15/2017 11:13 AM 5053 Update-MarkdownHelp.yml +-a---- 6/15/2017 11:13 AM 4661 Update-MarkdownHelpModule.yml +-a---- 6/15/2017 11:13 AM 3350 Update-MarkdownHelpSchema.yml +``` + +This will both read and write the files in the specified -Encoding. +The -Force parameter will overwrite files that already exist. + +## PARAMETERS + +### -Encoding +Specifies the character encoding for your external help file. +Specify a **System.Text.Encoding** object. +For more information, see [Character Encoding in the .NET Framework](https://msdn.microsoft.com/en-us/library/ms404377.aspx) in the Microsoft Developer Network. +For example, you can control Byte Order Mark (BOM) preferences. +For more information, see [Using PowerShell to write a file in UTF-8 without the BOM](http://stackoverflow.com/questions/5596982/using-powershell-to-write-a-file-in-utf-8-without-the-bom) at the Stack Overflow community. + +```yaml +Type: Encoding +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Force +Indicates that this cmdlet overwrites an existing file that has the same name. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Path +Specifies an array of paths of markdown files or folders. +This cmdlet creates external help based on these files and folders. + +```yaml +Type: String[] +Parameter Sets: (All) +Aliases: + +Required: True +Position: 1 +Default value: None +Accept pipeline input: True (ByPropertyName, ByValue) +Accept wildcard characters: False +``` + +### -OutputFolder +Specifies the folder to create the YAML files in + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: True +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.String[] +You can pipe an array of paths to this cmdlet. + +## OUTPUTS + +### IResult#System.IO.FileInfo[] +This cmdlet returns a **FileInfo[]** object for created files. + +## NOTES + +## RELATED LINKS From 757bb5fb686e01c130ffbf6e1e24a6ab7591532c Mon Sep 17 00:00:00 2001 From: Aditya Patwardhan Date: Fri, 2 Jul 2021 10:40:16 -0700 Subject: [PATCH 04/27] Allow `New-YamlHelp` to generate YAML for Common Parameters (#547) --- src/Markdown.MAML/Renderer/YamlRenderer.cs | 11 +++++++++++ test/Markdown.MAML.Test/Renderer/YamlRendererTests.cs | 6 +++--- test/Pester/PlatyPs.Tests.ps1 | 2 +- 3 files changed, 15 insertions(+), 4 deletions(-) diff --git a/src/Markdown.MAML/Renderer/YamlRenderer.cs b/src/Markdown.MAML/Renderer/YamlRenderer.cs index f85000ab..87493a7a 100644 --- a/src/Markdown.MAML/Renderer/YamlRenderer.cs +++ b/src/Markdown.MAML/Renderer/YamlRenderer.cs @@ -31,6 +31,17 @@ public static string MamlModelToString(MamlCommand mamlCommand) Syntaxes = mamlCommand.Syntax.Select(CreateSyntax).ToList() }; + if (mamlCommand.SupportCommonParameters) + { + var commonParam = new YamlParameter + { + Name = Markdown.MAML.Resources.MarkdownStrings.CommonParametersToken, + Description = Markdown.MAML.Resources.MarkdownStrings.CommonParametersText + }; + + model.OptionalParameters.Add(commonParam); + } + using (var writer = new StringWriter()) { serializer.Serialize(writer, model); diff --git a/test/Markdown.MAML.Test/Renderer/YamlRendererTests.cs b/test/Markdown.MAML.Test/Renderer/YamlRendererTests.cs index 6f2f081a..81fde57f 100644 --- a/test/Markdown.MAML.Test/Renderer/YamlRendererTests.cs +++ b/test/Markdown.MAML.Test/Renderer/YamlRendererTests.cs @@ -119,9 +119,9 @@ public void RenderProducesOptionalParameters() var writtenModel = deserializer.Deserialize(output); - Assert.Single(writtenModel.OptionalParameters); + Assert.Equal(2, writtenModel.OptionalParameters.Count); - var optionalParameter = writtenModel.OptionalParameters.Single(); + var optionalParameter = writtenModel.OptionalParameters.First(); var expectedParameter = model.Parameters.Single(p => !p.Required); Assert.Equal(expectedParameter.Globbing, optionalParameter.AcceptWildcardCharacters); @@ -197,7 +197,7 @@ public void RenderProducesSyntaxes() var syntax = writtenModel.Syntaxes.Single(); Assert.Equal(model.Syntax.Single().ParameterSetName, syntax.ParameterValueGroup); - + Assert.Single(syntax.Parameters); Assert.Equal(model.Syntax.Single().Parameters.Single().Name, syntax.Parameters.Single()); } diff --git a/test/Pester/PlatyPs.Tests.ps1 b/test/Pester/PlatyPs.Tests.ps1 index c5780914..2e5b7e89 100644 --- a/test/Pester/PlatyPs.Tests.ps1 +++ b/test/Pester/PlatyPs.Tests.ps1 @@ -1621,7 +1621,7 @@ Describe 'New-YamlHelp' { $yamlModel.RequiredParameters[0].Name | Should Be 'Path' $yamlModel.RequiredParameters[1].Name | Should Be 'OutputFolder' - $yamlModel.OptionalParameters.Count | Should Be 2 + $yamlModel.OptionalParameters.Count | Should Be 3 $yamlModel.OptionalParameters[0].Name | Should Be 'Encoding' $yamlModel.OptionalParameters[1].Name | Should Be 'Force' From 4c077e072a9669a48a277e4fb33d19d8523844a8 Mon Sep 17 00:00:00 2001 From: Aditya Patwardhan Date: Fri, 2 Jul 2021 11:03:20 -0700 Subject: [PATCH 05/27] Update CHANGELOG for 0.14.2 release (#548) --- CHANGELOG.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 930bbc0b..54d535e0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,6 +3,16 @@ CHANGELOG ## Not released +# 0.14.2 + +- Add HelpInfoUri for platyPS module +- CI changes to exclude build on v2 branch +- Fix issues with module and external help file metadata + - Escape # in output ype + - Allow hyphen in module name + - Make sure for script module .psm1 is added to the external help file metadata for nested module +- New-Yaml help generates YAML for common parameters + # 0.14.1 - Fix appveyor build script From 2d1dbe80f319f644596d0ca440f9db784eaabfc1 Mon Sep 17 00:00:00 2001 From: Aditya Patwardhan Date: Thu, 12 Oct 2017 10:50:15 -0700 Subject: [PATCH 06/27] Reset the expected value --- test/Pester/PlatyPs.Tests.ps1 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/test/Pester/PlatyPs.Tests.ps1 b/test/Pester/PlatyPs.Tests.ps1 index 2e5b7e89..0018b085 100644 --- a/test/Pester/PlatyPs.Tests.ps1 +++ b/test/Pester/PlatyPs.Tests.ps1 @@ -389,7 +389,7 @@ Write-Host 'Hello World!' } It 'generates markdown with correct synopsis' { - ($content | Where-Object {$_ -eq 'Adds a file name extension to a supplied name.'} | Measure-Object).Count | Should Be 2 + ($content | Where-Object {$_ -eq 'Adds a file name extension to a supplied name.'} | Measure-Object).Count | Should Be 1 } It 'generates markdown with correct help description specified by HelpMessage attribute' { From 824c3e13587ee70383973db25aa4981e918d146d Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Mon, 11 Apr 2022 10:58:52 -0500 Subject: [PATCH 07/27] Update issue templates --- .github/ISSUE_TEMPLATE.md | 23 ------- .github/ISSUE_TEMPLATE/Bug_Report.yaml | 70 +++++++++++++++++++++ .github/ISSUE_TEMPLATE/Feature_Request.yaml | 20 ++++++ .github/ISSUE_TEMPLATE/config.yml | 8 +++ 4 files changed, 98 insertions(+), 23 deletions(-) delete mode 100644 .github/ISSUE_TEMPLATE.md create mode 100644 .github/ISSUE_TEMPLATE/Bug_Report.yaml create mode 100644 .github/ISSUE_TEMPLATE/Feature_Request.yaml create mode 100644 .github/ISSUE_TEMPLATE/config.yml diff --git a/.github/ISSUE_TEMPLATE.md b/.github/ISSUE_TEMPLATE.md deleted file mode 100644 index 335a290d..00000000 --- a/.github/ISSUE_TEMPLATE.md +++ /dev/null @@ -1,23 +0,0 @@ - - -Steps to reproduce ------------------- - - -Expected behavior ------------------ - - -Actual behavior ---------------- - - -Environment data ----------------- - - - -v0.5.0 diff --git a/.github/ISSUE_TEMPLATE/Bug_Report.yaml b/.github/ISSUE_TEMPLATE/Bug_Report.yaml new file mode 100644 index 00000000..79db15b4 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/Bug_Report.yaml @@ -0,0 +1,70 @@ +name: Bug report 🐛 +description: Report errors or unexpected behavior 🤔 +labels: Needs-Triage +body: +- type: markdown + attributes: + value: > + This repository is **ONLY** for PlatyPS issues. +- type: checkboxes + attributes: + label: Prerequisites + options: + - label: Write a descriptive title. + required: true + - label: Make sure you are able to repro it on the [latest released version](https://github.com/PowerShell/platyPS/releases) + required: true + - label: Search the existing issues. + required: true +- type: textarea + attributes: + label: Steps to reproduce + description: > + List of steps, sample code, failing test or link to a project that reproduces the behavior. + Make sure you place a stack trace inside a code (```) block to avoid linking unrelated issues. + placeholder: > + I am experiencing a problem with X. + I think Y should be happening but Z is actually happening. + validations: + required: true +- type: textarea + attributes: + label: Expected behavior + render: console + placeholder: | + PS> 2 + 2 + 4 + validations: + required: true +- type: textarea + attributes: + label: Actual behavior + render: console + placeholder: | + PS> 2 + 2 + 5 + validations: + required: true +- type: textarea + attributes: + label: Error details + description: Paste verbatim output from `Get-Error` if PowerShell returns an error. + render: console + placeholder: PS> Get-Error +- type: textarea + attributes: + label: Environment data + description: Paste verbatim output from `Get-Modules` and `$PSVersionTable` below. + render: powershell + placeholder: | + PS> Get-Module PlatyPS -ListAvailable + PS> $PSVersionTable + validations: + required: true +- type: textarea + attributes: + label: Visuals + description: > + Please upload images or animations that can be used to reproduce issues in the area below. + Try the [Steps Recorder](https://support.microsoft.com/en-us/windows/record-steps-to-reproduce-a-problem-46582a9b-620f-2e36-00c9-04e25d784e47) + on Windows or [Screenshot](https://support.apple.com/en-us/HT208721) on macOS. diff --git a/.github/ISSUE_TEMPLATE/Feature_Request.yaml b/.github/ISSUE_TEMPLATE/Feature_Request.yaml new file mode 100644 index 00000000..c8e4cec3 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/Feature_Request.yaml @@ -0,0 +1,20 @@ +name: Feature Request / Idea 🚀 +description: Suggest a new feature or improvement (this does not mean you have to implement it) +labels: [Issue-Enhancement, Needs-Triage] +body: +- type: textarea + attributes: + label: Summary of the new feature / enhancement + description: > + A clear and concise description of what the problem is that the + new feature would solve. Try formulating it in user story style + (if applicable). + placeholder: "'As a user I want X so that Y...' with X being the being the action and Y being the value of the action." + validations: + required: true +- type: textarea + attributes: + label: Proposed technical implementation details (optional) + placeholder: > + A clear and concise description of what you want to happen. + Consider providing an example PowerShell experience with expected result. diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 00000000..b1b2260b --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,8 @@ +blank_issues_enabled: false +contact_links: + - name: Windows PowerShell + url: https://support.microsoft.com/windows/send-feedback-to-microsoft-with-the-feedback-hub-app-f59187f8-8739-22d6-ba93-f66612949332 + about: Windows PowerShell issues or suggestions. + - name: Support + url: https://github.com/PowerShell/PowerShell/blob/master/.github/SUPPORT.md + about: PowerShell Support Questions/Help From e21676add63e083c4935bdbf3306decda91fd3d0 Mon Sep 17 00:00:00 2001 From: Michael Lombardi Date: Tue, 14 Jun 2022 16:11:47 -0500 Subject: [PATCH 08/27] (AB-1952370) Add link to docs repo in issue picker Prior to this change the issue picker did not enumerate where to file documentation issues or requests. This change extends the list of links for the issue picker to include a direct link to the documentation repository to file a new issue. --- .github/ISSUE_TEMPLATE/config.yml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index b1b2260b..29496d2a 100644 --- a/.github/ISSUE_TEMPLATE/config.yml +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -6,3 +6,6 @@ contact_links: - name: Support url: https://github.com/PowerShell/PowerShell/blob/master/.github/SUPPORT.md about: PowerShell Support Questions/Help + - name: Documentation Issue + url: https://github.com/MicrosoftDocs/PowerShell-Docs-Modules/issues/new + about: Please open issues on documentation for PlatyPS here. From 3ea4c18f5e1a7ff0658ed794ab9fb1623d51a5bf Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Wed, 22 Jun 2022 10:11:19 -0500 Subject: [PATCH 09/27] Update config.yml --- .github/ISSUE_TEMPLATE/config.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index 29496d2a..2e867bc2 100644 --- a/.github/ISSUE_TEMPLATE/config.yml +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -7,5 +7,5 @@ contact_links: url: https://github.com/PowerShell/PowerShell/blob/master/.github/SUPPORT.md about: PowerShell Support Questions/Help - name: Documentation Issue - url: https://github.com/MicrosoftDocs/PowerShell-Docs-Modules/issues/new + url: https://github.com/MicrosoftDocs/PowerShell-Docs-Modules/issues/choose/new about: Please open issues on documentation for PlatyPS here. From 624a22a48edc9de42f8da7cfb8f6cc4ce3eb16d0 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Wed, 22 Jun 2022 10:11:58 -0500 Subject: [PATCH 10/27] Update config.yml --- .github/ISSUE_TEMPLATE/config.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index 2e867bc2..089e6e40 100644 --- a/.github/ISSUE_TEMPLATE/config.yml +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -7,5 +7,5 @@ contact_links: url: https://github.com/PowerShell/PowerShell/blob/master/.github/SUPPORT.md about: PowerShell Support Questions/Help - name: Documentation Issue - url: https://github.com/MicrosoftDocs/PowerShell-Docs-Modules/issues/choose/new + url: https://github.com/MicrosoftDocs/PowerShell-Docs-Modules/issues/new/choose about: Please open issues on documentation for PlatyPS here. From 34339d26c8659300ca629f0efb1bfa5746869812 Mon Sep 17 00:00:00 2001 From: Aditya Patwardhan Date: Tue, 28 Jun 2022 15:35:23 -0700 Subject: [PATCH 11/27] OPS Schema updates (#572) --- specs/PSCommand.schema-new.json | 261 ++++++++++++++++++++++++++++++++ specs/PSCommand.schema.json | 215 ++++++++++++++++++++++++++ specs/Schema-Notes.md | 135 +++++++++++++++++ 3 files changed, 611 insertions(+) create mode 100644 specs/PSCommand.schema-new.json create mode 100644 specs/PSCommand.schema.json create mode 100644 specs/Schema-Notes.md diff --git a/specs/PSCommand.schema-new.json b/specs/PSCommand.schema-new.json new file mode 100644 index 00000000..aaa0f5b3 --- /dev/null +++ b/specs/PSCommand.schema-new.json @@ -0,0 +1,261 @@ +{ + "title": "PowershellCmdlet", + "$schema": "https://dotnet.github.io/docfx/schemas/v1.0/schema.json#", + "version": "1.0.0", + "description": "The schema for powershell cmdlet page", + "id": "https://static.docs.com/ui/latest/schemas/PowershellCmdlet.schema.json", + "type": "object", + "additionalProperties": false, + "required": ["name", "module", "uid"], // UID is added by OPS team. will not be included in the YAML generated by New-YamlHelp + "renderType": "content", + "archivable": false, + "properties": { + "applicable": { + "items": { + "type": "string" + }, + "minItems": 1, + "type": "array" + }, + "description": { // Is this Description? No change. Can code blocks be included here? + "type": "string", + "contentType": "markdown", + "tags": ["localizable"] + }, + "examples": { + "items": { + "additionalProperties": false, + "required": ["title", "description"], // We need it to be title and block of markdown, which includes 1 or more code blocks and 0 or more paragraphs + "properties": { + "title": { + "type": "string", + "tags": ["localizable"] + }, + "description": { + "type": "string", + "contentType": "markdown", + "tags": ["localizable"] + } + }, + "type": "object" + }, + "minItems": 1, + "type": "array" + }, + "inputs": { + "items": { + "additionalProperties": false, + "required": ["name", "description"], + "properties": { + "name": { + "type": "string", + "contentType": "markdown" + }, + "description": { + "type": "string", + "contentType": "markdown", + "tags": ["localizable"] + } + }, + "type": "object" + }, + "minItems": 0, // Cmdlet can have no inputs, but the "Inputs" section must exist. + "type": "array" + }, + "links": { + "items": { + "additionalProperties": false, + "required": ["href", "text"], + "properties": { + "href": { + "type": "string", + "contentType": "href" + }, + "text": { + "type": "string", + "tags": ["localizable"] + } + }, + "type": "object" + }, + "minItems": 1, + "type": "array" + }, + "metadata": { // this YAML front matter + "required": ["title", "external help file", "locale", "module name", "ms.date", "oneline version", "schema"], // 'external help file' must exists but can be blank. + "properties": { + "description": { // what is this for? For SEO? + "type": "string", + "tags": ["localizable"] + }, + "title": { + "type": "string", + "tags": ["localizable"] + }, + "external help file": { + "items": { + "type": "string" + }, + "minItems": 0 + }, + "locale": { + "type": "string" + }, + "module name":{ + "type": "string" + }, + "ms.date": { + "type": "string" + }, + "online version": { + "type": "string", + "contentType": "href" + }, + "schema": { + "type": "string" + } + }, + "type": "object" + }, + "module": { + "type": "string", + "contentType": "xref" + }, + "name": { // Is this Title? No change. + "type": "string" + }, + "notes": { + "type": "string", + "contentType": "markdown", + "tags": ["localizable"] + }, + "outputs": { + "items": { + "additionalProperties": false, + "required": ["name", "description"], + "properties": { + "name": { + "type": "string", + "contentType": "markdown" + }, + "description": { + "type": "string", + "contentType": "markdown", + "tags": ["localizable"] + } + }, + "type": "object" + }, + "minItems": 1, + "type": "array" + }, + "parameters": { + "items": { + "additionalProperties": false, + "required": ["name", "description", "type", "position"], + "properties": { + "name": { + "type": "string" + }, + "summary": { + "type": "string", + "contentType": "markdown", + "tags": ["localizable"] + }, + "description": { + "type": "string", + "contentType": "markdown", + "tags": ["localizable"] + }, + "isRequired": { + "type": "boolean" + }, + "applicable": { + "items": { + "type": "string" + }, + "minItems": 1, + "type": "array" + }, + "type": { + "type": "string" + }, + "aliases": { + "type": "string" + }, + "parameterValueGroup": { // is this ParameterSetName? + "type": "string" + }, + "position": { // this could be different per parameter set + "type": "string" + }, + "defaultValue": { + "type": "string" + }, + "pipelineInput": { // this could be different per parameter set + "type": "string" + }, + "acceptWildcardCharacters": { + "type": "boolean" + }, + "valueFrom": { // what is this? + "type": "string" + }, + "acceptedValues": { + "value": { + "type": "string" + }, + "type": "array", + "minItems": 1 + }, + "confirmImpact": { + "type": "string" + } + }, + "type": "object" + }, + "minItems": 1, + "type": "array" + }, + "commonParameters": { + "parameters": { + "type": "string", + "contentType": "markdown" + }, + "type":"object", + "minItems": 1, + "maxItems": 1 + }, + "summary": { // is this Synopsis? No change. + "type": "string", + "contentType": "markdown", + "tags": ["localizable"] + }, + "syntaxes": { + "items": [ + { + "items": { + "required": ["Parameter Set name", "Parameters"], + "properties": { + "Parameter Set name": { + "type": "string" + }, + "Parameters": { + "type": "string" + } + } + } + } + ], + "minItems": 1, + "type": "array" + } + }, + "uid": { + "type": "string", + "contentType": "uid" + } + }, + "metadata": "/metadata", + "xrefProperties": ["name", "summary"] +} diff --git a/specs/PSCommand.schema.json b/specs/PSCommand.schema.json new file mode 100644 index 00000000..8636f27e --- /dev/null +++ b/specs/PSCommand.schema.json @@ -0,0 +1,215 @@ +{ + "title": "PowershellCmdlet", + "$schema": "https://dotnet.github.io/docfx/schemas/v1.0/schema.json#", + "version": "1.0.0", + "description": "The schema for powershell cmdlet page", + "id": "https://static.docs.com/ui/latest/schemas/PowershellCmdlet.schema.json", + "type": "object", + "additionalProperties": false, + "required": ["name", "module", "uid"], + "renderType": "content", + "archivable": false, + "properties": { + "applicable": { + "items": { + "type": "string" + }, + "minItems": 1, + "type": "array" + }, + "description": { + "type": "string", + "contentType": "markdown", + "tags": ["localizable"] + }, + "examples": { + "items": { + "additionalProperties": false, + "required": ["title", "summary", "description"], + "properties": { + "title": { + "type": "string", + "tags": ["localizable"] + }, + "summary": { + "type": "string", + "contentType": "markdown", + "tags": ["localizable"] + }, + "code": { + "type": "string" + }, + "description": { + "type": "string", + "contentType": "markdown", + "tags": ["localizable"] + } + }, + "type": "object" + }, + "minItems": 1, + "type": "array" + }, + "inputs": { + "items": { + "additionalProperties": false, + "required": ["name", "description"], + "properties": { + "name": { + "type": "string", + "contentType": "markdown" + }, + "description": { + "type": "string", + "contentType": "markdown", + "tags": ["localizable"] + } + }, + "type": "object" + }, + "minItems": 1, + "type": "array" + }, + "links": { + "items": { + "additionalProperties": false, + "required": ["href", "text"], + "properties": { + "href": { + "type": "string", + "contentType": "href" + }, + "text": { + "type": "string", + "tags": ["localizable"] + } + }, + "type": "object" + }, + "minItems": 1, + "type": "array" + }, + "metadata": { + "properties": { + "description": { + "type": "string", + "tags": ["localizable"] + }, + "title": { + "type": "string", + "tags": ["localizable"] + } + }, + "type": "object" + }, + "module": { + "type": "string", + "contentType": "xref" + }, + "name": { + "type": "string" + }, + "notes": { + "type": "string", + "contentType": "markdown", + "tags": ["localizable"] + }, + "outputs": { + "items": { + "additionalProperties": false, + "required": ["name", "description"], + "properties": { + "name": { + "type": "string", + "contentType": "markdown" + }, + "description": { + "type": "string", + "contentType": "markdown", + "tags": ["localizable"] + } + }, + "type": "object" + }, + "minItems": 1, + "type": "array" + }, + "parameters": { + "items": { + "additionalProperties": false, + "required": ["name", "description", "type", "position"], + "properties": { + "name": { + "type": "string" + }, + "summary": { + "type": "string", + "contentType": "markdown", + "tags": ["localizable"] + }, + "description": { + "type": "string", + "contentType": "markdown", + "tags": ["localizable"] + }, + "isRequired": { + "type": "boolean" + }, + "applicable": { + "items": { + "type": "string" + }, + "minItems": 1, + "type": "array" + }, + "type": { + "type": "string", + "contentType": "markdown" + }, + "aliases": { + "type": "string" + }, + "parameterValueGroup": { + "type": "string" + }, + "position": { + "type": "string" + }, + "defaultValue": { + "type": "string" + }, + "pipelineInput": { + "type": "boolean" + }, + "acceptWildcardCharacters": { + "type": "boolean" + }, + "valueFrom": { + "type": "string" + } + }, + "type": "object" + }, + "minItems": 1, + "type": "array" + }, + "summary": { + "type": "string", + "contentType": "markdown", + "tags": ["localizable"] + }, + "syntaxes": { + "items": { + "type": "string" + }, + "minItems": 1, + "type": "array" + }, + "uid": { + "type": "string", + "contentType": "uid" + } + }, + "metadata": "/metadata", + "xrefProperties": ["name", "summary"] +} diff --git a/specs/Schema-Notes.md b/specs/Schema-Notes.md new file mode 100644 index 00000000..2c279340 --- /dev/null +++ b/specs/Schema-Notes.md @@ -0,0 +1,135 @@ +This the current layout of the markdown for a Cmdlet with notes: + +YAML Frontmatter + +- Need to not error on PlatyPS required keys (external help file, Locale, Module Name, ms.date, + online version, schema, title) +- What should we do about description? - currently copied by OPS from Description below +- Mapping to existing JSON schema: properties/metadata + +Title + +- Type: H1 +- Required: Y +- Count: 1 +- Mapping to existing JSON schema: properties/name + +Synopsis + +- Type: H2 +- Required: Y +- Count: 1 +- Mapping to existing JSON schema: properties/summary + +Syntax + +- Type: H2 +- Required: Y +- Count: 1 +- Required: No changes +- Mapping to existing JSON schema: properties/syntaxes +- Notes: Contains 1 or more of the following: + - Parameter Set name + - Type: H3 + - Required: Y + - Count: 1-N + - Parameter Sets - should be sorted starting with Default, then by Alpha +- Parameters (in syntax block) + - Syntax block + - What format do you want? - Currently MAML2Yaml is using the strings from the code block instead + of a Yaml data model. Prefer the string model. + +Description + +- Type: H2 +- Required: Y +- Count: 1 +- Mapping to existing JSON schema: properties/description +- Allow any markdown content type except Headers + +Examples + +- Type: H2 +- Required: Y +- Count: 1 +- Mapping to existing JSON schema: properties/examples +- Notes: Contains 1 or more of the following + - Example + - Type: H3 + - Required: Y + - Count: 1-N + - Should require one code block at minimum per example + - Should allow a mix of markdown code blocks and paragraphs in any order + +Parameters + +- Type: H2 +- Required: Y +- Count: 1 +- Mapping to existing JSON schema: properties/parameters +- Parameters should be sorted Alphabetically followed by `-Confirm` and `-WhatIf` (when included). + PlatyPS has the `-AlphabeticParamsOrder` parameter that produces this order. +- Notes: Contains 1 or more of the following + - Parameter + - Type: H3 + - Required: Y + - Count: 1-N + - Required: Yaml block should include: + - Parameter Set Name + - Position can be different per parameter set + - Add **AcceptedValues** - Should display enumerated values of parameter (like ValidateSet) + - maps to properties/parameters/parameterValueGroup? + - Add **ConfirmImpact** - Impact severity should be reflected and displayed to inform defaults + for `-Confirm` + - what is **valueFrom** in JSON schema? + - **pipelineInput** is currently a boolean. The value can be different per parameter set to + the type needs to be a string + +Common Parameters + +- Type: H3 +- Required: Y +- Count: 1 +- Notes: + - this is missing from the schema - need to define it + - The content should be the markdown description provided in the file + +Inputs + +- Type: H2 +- Required: Y +- Count: 1 +- Mapping to existing JSON schema: properties/inputs +- Notes: Contains 0 or more of the following: + - Input type + - Type: H3 + - Required: N + - Count: 0-N + +Outputs + +- Type: H2 +- Required: Y +- Count: 1 +- Mapping to existing JSON schema: properties/outputs +- Notes: Contains 0 or more of the following: + - Output type + - Type: H3 + - Required: N + - Count: 0-N + +Notes + +- Type: H2 +- Required: N +- Mapping to existing JSON schema: properties/notes +- Count: 1 header with 0 or more markdown elements (excluding header types) + +Related links + +- Type: H3 +- Required: Y +- Count: 1 +- Mapping to existing JSON schema: properties/links +- Link list should use a bullet list +- Should support markdown paragraphs not just links From ac72fe28cdcc0ace9f0cc9460e712a3e013878f1 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Mon, 29 Aug 2022 12:33:14 -0500 Subject: [PATCH 12/27] Add Alias support to spec docs --- specs/alias-prototype.md | 26 ++++++++++++++++++++++++++ specs/platyps_2.0_update.md | 30 ++++++++++++++++++++++-------- 2 files changed, 48 insertions(+), 8 deletions(-) create mode 100644 specs/alias-prototype.md diff --git a/specs/alias-prototype.md b/specs/alias-prototype.md new file mode 100644 index 00000000..68b65ccc --- /dev/null +++ b/specs/alias-prototype.md @@ -0,0 +1,26 @@ +--- +external help file: Microsoft.PowerShell.Commands.Management.dll-Help.xml +Locale: en-US +Module Name: Microsoft.PowerShell.Management +ms.date: 03/27/2020 +online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.management/get-childitem?view=powershell-7.2&WT.mc_id=ps-gethelp +schema: 2.0.0 +title: Get-ChildItem +alias: + - all: dir, gci + - windows: ls + - macos: + - linux: +--- +# Get-ChildItem + +## SYNOPSIS + +Gets the items and child items in one or more specified locations. + +## ALIASES + +This cmdlet supports the following aliases on the following platforms: + +- All platforms: `dir`, `gci` +- Windows: `ls` diff --git a/specs/platyps_2.0_update.md b/specs/platyps_2.0_update.md index 11f2d53c..d15cdd42 100644 --- a/specs/platyps_2.0_update.md +++ b/specs/platyps_2.0_update.md @@ -1,9 +1,6 @@ --- -RFC: RFCXXXX -Author: Jason Helmick -Status: Draft -Area: -Comments Due: +title: PlatyPS 2.0 specification +ms.date: 08/29/2022 --- # PlatyPS 2.0 Update @@ -80,6 +77,7 @@ The following sections outline schema changes for the Help file. | ------------------ | ----- | --------- | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Title | H1 | Y | 1 | - Add reflection of cmdlet platform/alias based on platform
- Could do as Yaml block with Windows: macOS: Linux: (See block below table) | | Synopsis | H2 | Y | 1 | - No changes | +| Aliases | H2 | Y | 1 | - New header to support documentation for cmdlet aliases | | Syntax | H2 | Y | 1 | - No changes | | Parameter Set Name | H3 | Y | 1-N | - Parameter Sets - should be sorted starting with Default, then by Alpha
- Parameters (in syntax block) - Should be sorted Positional, Required, then by Alpha | | Description | H2 | Y | 1 | - Allow any content type
- No Headers H2, H3, H4 | @@ -118,11 +116,27 @@ DontShow: True ```yaml - aliases: - windows: gci, dir, ls - macOS: gci, dir - linux: gci, dir + - all: dir, gci + - windows: ls + - macOS: + - linux: ``` + Add new H2 for documenting aliases. + + ```markdown + ## ALIASES + + This cmdlet supports the following aliases on the following platforms: + + - All platforms: `dir`, `gci` + - Windows: `ls` + ``` + + See [alias-prototype](alias-prototype.md) for an example. + + See [Issue #585](https://github.com/PowerShell/platyPS/issues/585). + 1. Have a some schema format for representing the availability of the cmdlet for a platform (win/mac/linux). Could be one or more. Default to Windows but editable by the author. From 8eea6f37e6be71de208a937f420811f65fe005d6 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Wed, 12 Oct 2022 14:39:23 -0500 Subject: [PATCH 13/27] Update alias spec and examples --- specs/alias-prototype.md | 29 ++++++++++++++++++++++++----- specs/platyps_2.0_update.md | 17 ++++++++--------- 2 files changed, 32 insertions(+), 14 deletions(-) diff --git a/specs/alias-prototype.md b/specs/alias-prototype.md index 68b65ccc..790df72c 100644 --- a/specs/alias-prototype.md +++ b/specs/alias-prototype.md @@ -7,10 +7,10 @@ online version: https://docs.microsoft.com/powershell/module/microsoft.powershel schema: 2.0.0 title: Get-ChildItem alias: - - all: dir, gci - - windows: ls - - macos: - - linux: + all: [dir, gci] + windows: [ls] + macos: + linux: --- # Get-ChildItem @@ -20,7 +20,26 @@ Gets the items and child items in one or more specified locations. ## ALIASES -This cmdlet supports the following aliases on the following platforms: +PowerShell includes the following aliases for `Get-ChildItem`: - All platforms: `dir`, `gci` - Windows: `ls` + +## SYNTAX + +### Items (Default) + +``` +Get-ChildItem [[-Path] ] [[-Filter] ] [-Include ] [-Exclude ] + [-Recurse] [-Depth ] [-Force] [-Name] [-Attributes ] + [-FollowSymlink] [-Directory] [-File] [-Hidden] [-ReadOnly] [-System] [] +``` + +### LiteralItems + +``` +Get-ChildItem [[-Filter] ] -LiteralPath [-Include ] + [-Exclude ] [-Recurse] [-Depth ] [-Force] [-Name] + [-Attributes ] [-FollowSymlink] [-Directory] [-File] [-Hidden] + [-ReadOnly] [-System] [] +``` diff --git a/specs/platyps_2.0_update.md b/specs/platyps_2.0_update.md index d15cdd42..311ce528 100644 --- a/specs/platyps_2.0_update.md +++ b/specs/platyps_2.0_update.md @@ -1,6 +1,6 @@ --- title: PlatyPS 2.0 specification -ms.date: 08/29/2022 +ms.date: 10/12/2022 --- # PlatyPS 2.0 Update @@ -112,14 +112,14 @@ DontShow: True 1. Have a way to document aliases for the cmdlet. Today we only document aliases for parameters. This is difficult to discover, so don't need `*-MarkdownHelp` cmdlets to create it but the schema - needs to support it. The author can add the information. For example: + needs to support it. The author can add the information to the YAML frontmatter. For example: ```yaml - - aliases: - - all: dir, gci - - windows: ls - - macOS: - - linux: + aliases: + all: [dir, gci] + windows: [ls] + macOS: + linux: ``` Add new H2 for documenting aliases. @@ -127,7 +127,7 @@ DontShow: True ```markdown ## ALIASES - This cmdlet supports the following aliases on the following platforms: + PowerShell includes the following aliases for `Get-ChildItem`: - All platforms: `dir`, `gci` - Windows: `ls` @@ -336,4 +336,3 @@ TODO ## Issues for this milestone [2.0-consider](https://github.com/PowerShell/platyPS/issues?q=is%3Aopen+is%3Aissue+milestone%3A2.0-consider) - From 06194a98ea9b10772b2c5c99502ca4a7f31aedfc Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Wed, 12 Oct 2022 14:46:40 -0500 Subject: [PATCH 14/27] Update note about MAML conversion --- specs/platyps_2.0_update.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/specs/platyps_2.0_update.md b/specs/platyps_2.0_update.md index 311ce528..4366d4ae 100644 --- a/specs/platyps_2.0_update.md +++ b/specs/platyps_2.0_update.md @@ -135,6 +135,13 @@ DontShow: True See [alias-prototype](alias-prototype.md) for an example. + > [!NOTE] + > Since the XSD for MAML is fixed we cannot support the new H2 section in the conversion to MAML. + > Instead we will keep the H2 in the markdown source and in the conversion to YAML. But we need + > to special case the conversion to MAML. The H2 Aliases section can be prepended to the NOTES + > section as a `` item. This means the information will appear in the NOTES section + > of `Get-Help` output. + See [Issue #585](https://github.com/PowerShell/platyPS/issues/585). 1. Have a some schema format for representing the availability of the cmdlet for a platform From 7e4665f2c777ebfa98965d0e7a47ec14ed718449 Mon Sep 17 00:00:00 2001 From: Aditya Patwardhan Date: Wed, 11 Jan 2023 17:18:26 -0800 Subject: [PATCH 15/27] Update the YAML schema (#575) --- ....json => PowerShellCmdlet.schema-new.json} | 183 +++++++----------- ...hema.json => PowerShellCmdlet.schema.json} | 0 2 files changed, 70 insertions(+), 113 deletions(-) rename specs/{PSCommand.schema-new.json => PowerShellCmdlet.schema-new.json} (51%) rename specs/{PSCommand.schema.json => PowerShellCmdlet.schema.json} (100%) diff --git a/specs/PSCommand.schema-new.json b/specs/PowerShellCmdlet.schema-new.json similarity index 51% rename from specs/PSCommand.schema-new.json rename to specs/PowerShellCmdlet.schema-new.json index aaa0f5b3..ee060da2 100644 --- a/specs/PSCommand.schema-new.json +++ b/specs/PowerShellCmdlet.schema-new.json @@ -6,7 +6,7 @@ "id": "https://static.docs.com/ui/latest/schemas/PowershellCmdlet.schema.json", "type": "object", "additionalProperties": false, - "required": ["name", "module", "uid"], // UID is added by OPS team. will not be included in the YAML generated by New-YamlHelp + "required": ["name", "description", "examples", "metadata", "module", "summary", "syntaxes", "uid"], "renderType": "content", "archivable": false, "properties": { @@ -17,7 +17,7 @@ "minItems": 1, "type": "array" }, - "description": { // Is this Description? No change. Can code blocks be included here? + "description": { "type": "string", "contentType": "markdown", "tags": ["localizable"] @@ -25,7 +25,7 @@ "examples": { "items": { "additionalProperties": false, - "required": ["title", "description"], // We need it to be title and block of markdown, which includes 1 or more code blocks and 0 or more paragraphs + "required": ["title", "description"], "properties": { "title": { "type": "string", @@ -59,7 +59,7 @@ }, "type": "object" }, - "minItems": 0, // Cmdlet can have no inputs, but the "Inputs" section must exist. + "minItems": 1, "type": "array" }, "links": { @@ -81,38 +81,15 @@ "minItems": 1, "type": "array" }, - "metadata": { // this YAML front matter - "required": ["title", "external help file", "locale", "module name", "ms.date", "oneline version", "schema"], // 'external help file' must exists but can be blank. + "metadata": { "properties": { - "description": { // what is this for? For SEO? + "description": { "type": "string", "tags": ["localizable"] }, "title": { "type": "string", "tags": ["localizable"] - }, - "external help file": { - "items": { - "type": "string" - }, - "minItems": 0 - }, - "locale": { - "type": "string" - }, - "module name":{ - "type": "string" - }, - "ms.date": { - "type": "string" - }, - "online version": { - "type": "string", - "contentType": "href" - }, - "schema": { - "type": "string" } }, "type": "object" @@ -121,7 +98,7 @@ "type": "string", "contentType": "xref" }, - "name": { // Is this Title? No change. + "name": { "type": "string" }, "notes": { @@ -151,105 +128,85 @@ }, "parameters": { "items": { - "additionalProperties": false, - "required": ["name", "description", "type", "position"], - "properties": { - "name": { - "type": "string" - }, - "summary": { - "type": "string", - "contentType": "markdown", - "tags": ["localizable"] - }, - "description": { - "type": "string", - "contentType": "markdown", - "tags": ["localizable"] - }, - "isRequired": { - "type": "boolean" - }, - "applicable": { - "items": { + "parameterItems": { + "additionalProperties": false, + "required": ["name", "description", "type", "position", "parameterSetName"], + "properties": { + "name": { "type": "string" }, - "minItems": 1, - "type": "array" - }, - "type": { - "type": "string" - }, - "aliases": { - "type": "string" - }, - "parameterValueGroup": { // is this ParameterSetName? - "type": "string" - }, - "position": { // this could be different per parameter set - "type": "string" - }, - "defaultValue": { - "type": "string" - }, - "pipelineInput": { // this could be different per parameter set - "type": "string" - }, - "acceptWildcardCharacters": { - "type": "boolean" - }, - "valueFrom": { // what is this? - "type": "string" - }, - "acceptedValues": { - "value": { + "description": { + "type": "string", + "contentType": "markdown", + "tags": ["localizable"] + }, + "isRequired": { + "type": "boolean" + }, + "applicable": { + "items": { + "type": "string" + }, + "minItems": 1, + "type": "array" + }, + "type": { + "type": "string", + "contentType": "markdown" + }, + "aliases": { + "type": "string" + }, + "parameterValueGroup": { + "type": "string" + }, + "position": { + "type": "string" + }, + "defaultValue": { "type": "string" }, - "type": "array", - "minItems": 1 + "pipelineInput": { + "type": "string" + }, + "acceptWildcardCharacters": { + "type": "boolean" + }, + "parameterSetName": { + "type": "string" + }, + "confirmImpact": { + "type": "string" + } }, - "confirmImpact": { - "type": "string" - } + "minItems": 1, + "type": "array" }, - "type": "object" - }, - "minItems": 1, - "type": "array" - }, - "commonParameters": { - "parameters": { - "type": "string", - "contentType": "markdown" - }, - "type":"object", - "minItems": 1, - "maxItems": 1 + "commonParameters": { + "type": "string", + "contentType": "markdown" + } + } }, - "summary": { // is this Synopsis? No change. + "summary": { "type": "string", "contentType": "markdown", "tags": ["localizable"] }, "syntaxes": { - "items": [ - { - "items": { - "required": ["Parameter Set name", "Parameters"], - "properties": { - "Parameter Set name": { - "type": "string" - }, - "Parameters": { - "type": "string" - } - } + "items": { + "required": ["Parameter Set name", "Parameters"], + "properties": { + "Parameter Set name": { + "type": "string" + }, + "syntaxItem": { + "type": "string" } } - ], + }, "minItems": 1, "type": "array" - } }, "uid": { "type": "string", diff --git a/specs/PSCommand.schema.json b/specs/PowerShellCmdlet.schema.json similarity index 100% rename from specs/PSCommand.schema.json rename to specs/PowerShellCmdlet.schema.json From 412a0a8683b986194d616d533589bc2b5fd03fae Mon Sep 17 00:00:00 2001 From: xmdanni Date: Wed, 8 Feb 2023 09:11:20 +0800 Subject: [PATCH 16/27] Update OPS schema (#591) --- specs/PowerShellCmdlet.schema-new.json | 218 ----------------------- specs/PowershellCmdletV2.schema.json | 234 +++++++++++++++++++++++++ 2 files changed, 234 insertions(+), 218 deletions(-) delete mode 100644 specs/PowerShellCmdlet.schema-new.json create mode 100644 specs/PowershellCmdletV2.schema.json diff --git a/specs/PowerShellCmdlet.schema-new.json b/specs/PowerShellCmdlet.schema-new.json deleted file mode 100644 index ee060da2..00000000 --- a/specs/PowerShellCmdlet.schema-new.json +++ /dev/null @@ -1,218 +0,0 @@ -{ - "title": "PowershellCmdlet", - "$schema": "https://dotnet.github.io/docfx/schemas/v1.0/schema.json#", - "version": "1.0.0", - "description": "The schema for powershell cmdlet page", - "id": "https://static.docs.com/ui/latest/schemas/PowershellCmdlet.schema.json", - "type": "object", - "additionalProperties": false, - "required": ["name", "description", "examples", "metadata", "module", "summary", "syntaxes", "uid"], - "renderType": "content", - "archivable": false, - "properties": { - "applicable": { - "items": { - "type": "string" - }, - "minItems": 1, - "type": "array" - }, - "description": { - "type": "string", - "contentType": "markdown", - "tags": ["localizable"] - }, - "examples": { - "items": { - "additionalProperties": false, - "required": ["title", "description"], - "properties": { - "title": { - "type": "string", - "tags": ["localizable"] - }, - "description": { - "type": "string", - "contentType": "markdown", - "tags": ["localizable"] - } - }, - "type": "object" - }, - "minItems": 1, - "type": "array" - }, - "inputs": { - "items": { - "additionalProperties": false, - "required": ["name", "description"], - "properties": { - "name": { - "type": "string", - "contentType": "markdown" - }, - "description": { - "type": "string", - "contentType": "markdown", - "tags": ["localizable"] - } - }, - "type": "object" - }, - "minItems": 1, - "type": "array" - }, - "links": { - "items": { - "additionalProperties": false, - "required": ["href", "text"], - "properties": { - "href": { - "type": "string", - "contentType": "href" - }, - "text": { - "type": "string", - "tags": ["localizable"] - } - }, - "type": "object" - }, - "minItems": 1, - "type": "array" - }, - "metadata": { - "properties": { - "description": { - "type": "string", - "tags": ["localizable"] - }, - "title": { - "type": "string", - "tags": ["localizable"] - } - }, - "type": "object" - }, - "module": { - "type": "string", - "contentType": "xref" - }, - "name": { - "type": "string" - }, - "notes": { - "type": "string", - "contentType": "markdown", - "tags": ["localizable"] - }, - "outputs": { - "items": { - "additionalProperties": false, - "required": ["name", "description"], - "properties": { - "name": { - "type": "string", - "contentType": "markdown" - }, - "description": { - "type": "string", - "contentType": "markdown", - "tags": ["localizable"] - } - }, - "type": "object" - }, - "minItems": 1, - "type": "array" - }, - "parameters": { - "items": { - "parameterItems": { - "additionalProperties": false, - "required": ["name", "description", "type", "position", "parameterSetName"], - "properties": { - "name": { - "type": "string" - }, - "description": { - "type": "string", - "contentType": "markdown", - "tags": ["localizable"] - }, - "isRequired": { - "type": "boolean" - }, - "applicable": { - "items": { - "type": "string" - }, - "minItems": 1, - "type": "array" - }, - "type": { - "type": "string", - "contentType": "markdown" - }, - "aliases": { - "type": "string" - }, - "parameterValueGroup": { - "type": "string" - }, - "position": { - "type": "string" - }, - "defaultValue": { - "type": "string" - }, - "pipelineInput": { - "type": "string" - }, - "acceptWildcardCharacters": { - "type": "boolean" - }, - "parameterSetName": { - "type": "string" - }, - "confirmImpact": { - "type": "string" - } - }, - "minItems": 1, - "type": "array" - }, - "commonParameters": { - "type": "string", - "contentType": "markdown" - } - } - }, - "summary": { - "type": "string", - "contentType": "markdown", - "tags": ["localizable"] - }, - "syntaxes": { - "items": { - "required": ["Parameter Set name", "Parameters"], - "properties": { - "Parameter Set name": { - "type": "string" - }, - "syntaxItem": { - "type": "string" - } - } - }, - "minItems": 1, - "type": "array" - }, - "uid": { - "type": "string", - "contentType": "uid" - } - }, - "metadata": "/metadata", - "xrefProperties": ["name", "summary"] -} diff --git a/specs/PowershellCmdletV2.schema.json b/specs/PowershellCmdletV2.schema.json new file mode 100644 index 00000000..ac9626a4 --- /dev/null +++ b/specs/PowershellCmdletV2.schema.json @@ -0,0 +1,234 @@ +{ + "title": "PowershellCmdletV2", + "$schema": "https://dotnet.github.io/docfx/schemas/v1.0/schema.json#", + "version": "1.0.0", + "description": "The schema for powershell cmdlet page - version 2", + "id": "https://static.docs.com/ui/latest/schemas/PowershellCmdletV2.schema.json", + "type": "object", + "additionalProperties": false, + "required": ["name", "module", "uid"], // tend to only keep necessary items for OPS, may validate the rest through Docs.Validation service by contacting Megan Bradley + "renderType": "content", + "archivable": false, + "properties": { + "aliases": { + "type": "string", + "contentType": "markdown", + "tags": ["localizable"] + }, + "applicable": { + "items": { + "type": "string" + }, + "minItems": 1, + "type": "array" + }, + "description": { + "type": "string", + "contentType": "markdown", + "tags": ["localizable"] + }, + "examples": { // Remove something. For fixing the mixture of code and output, PlatyPS issue #576. This change should take effect along with or after integrating PlatyPS v2 New-YamlHelp, because current MAML2YAML generates summary from content. + "items": { + "additionalProperties": false, + "required": ["title", "description"], + "properties": { + "title": { + "type": "string", + "tags": ["localizable"] + }, + "description": { + "type": "string", + "contentType": "markdown", + "tags": ["localizable"] + } + }, + "type": "object" + }, + "minItems": 1, + "type": "array" + }, + "inputs": { + "items": { + "additionalProperties": false, + "required": ["name", "description"], + "properties": { + "name": { + "type": "string", + "contentType": "markdown" + }, + "description": { + "type": "string", + "contentType": "markdown", + "tags": ["localizable"] + } + }, + "type": "object" + }, + "minItems": 1, + "type": "array" + }, + "links": { + "items": { + "additionalProperties": false, + "required": ["href", "text"], + "properties": { + "href": { + "type": "string", + "contentType": "href" + }, + "text": { + "type": "string", + "tags": ["localizable"] + } + }, + "type": "object" + }, + "minItems": 1, + "type": "array" + }, + "metadata": { + "properties": { + "description": { + "type": "string", + "tags": ["localizable"] + }, + "title": { + "type": "string", + "tags": ["localizable"] + } + }, + "type": "object" + }, + "module": { + "type": "string", + "contentType": "xref" + }, + "name": { + "type": "string" + }, + "notes": { + "type": "string", + "contentType": "markdown", + "tags": ["localizable"] + }, + "outputs": { + "items": { + "additionalProperties": false, + "required": ["name", "description"], + "properties": { + "name": { + "type": "string", + "contentType": "markdown" + }, + "description": { + "type": "string", + "contentType": "markdown", + "tags": ["localizable"] + } + }, + "type": "object" + }, + "minItems": 1, + "type": "array" + }, + "parameters": { // Add & modify something. This change should take effect along with or after integrating PlatyPS v2 New-YamlHelp, because current MAML2YAML does not transform commonParameters into yaml from markdown. + "properties": { + "cmdletParameters": { // naming pending? use only a single word as the name if possible + "items": { + "additionalProperties": false, + "required": ["name", "description", "type", "position", "parameterValueGroup"], + "properties": { + "name": { + "type": "string" + }, + "description": { + "type": "string", + "contentType": "markdown", + "tags": ["localizable"] + }, + "isRequired": { + "type": "boolean" + }, + "applicable": { + "items": { + "type": "string" + }, + "minItems": 1, + "type": "array" + }, + "type": { + "type": "string", + "contentType": "markdown" + }, + "aliases": { + "type": "string" + }, + "parameterValueGroup": { + "items": { + "type": "string" + }, + "minItems": 1, + "type": "array" + }, + "parameterSetName": { + "type": "string" + }, + "position": { + "type": "string" + }, + "defaultValue": { + "type": "string" + }, + "pipelineInput": { // change from bool to string, need to change js and template + "type": "string" + }, + "acceptWildcardCharacters": { + "type": "boolean" + }, + "confirmImpact": { + "type": "string" + } + }, + "type": "object" + }, + "minItems": 1, + "type": "array" + }, + "commonParameters": { + "type": "string", + "contentType": "markdown", + "tags": ["localizable"] + } + }, + "type": "object" + }, + "summary": { + "type": "string", + "contentType": "markdown", + "tags": ["localizable"] + }, + "syntaxes": { // Change type and add properties. This change should take effect along with or after integrating PlatyPS v2 New-YamlHelp, because current MAML2YAML generates text for this part. + "items": { + "additionalProperties": false, + "required": ["parameterSetName", "syntax"], + "properties": { + "parameterSetName": { + "type": "string" + }, + "syntax": { // naming pending? use only a single word as the name if possible + "type": "string" + } + }, + "type": "object" + }, + "minItems": 1, + "type": "array" + }, + "uid": { + "type": "string", + "contentType": "uid" + } + }, + "metadata": "/metadata", + "xrefProperties": ["name", "summary"] +} From 3da7d3023b58bc896b8f22755f06ded3e480bdf3 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Thu, 9 Mar 2023 17:11:20 -0600 Subject: [PATCH 17/27] Add new metadata descriptions --- specs/platyps_2.0_update.md | 213 ++++++++++++++++++++++++++---------- 1 file changed, 155 insertions(+), 58 deletions(-) diff --git a/specs/platyps_2.0_update.md b/specs/platyps_2.0_update.md index 4366d4ae..1095a628 100644 --- a/specs/platyps_2.0_update.md +++ b/specs/platyps_2.0_update.md @@ -1,6 +1,6 @@ --- title: PlatyPS 2.0 specification -ms.date: 10/12/2022 +ms.date: 03/09/2023 --- # PlatyPS 2.0 Update @@ -20,12 +20,10 @@ This update includes the following goals: Priorities -- Fix schema so that it contains all of the Help Data we need while maintaining as much +- Fix schema so that it contains all the Help Data we need while maintaining as much compatibility as possible with PS 5.1 and Exchange - Switch markdown engine to markdig -- Fix OPS rendering problems (this may require specific changes in PlatyPS) - - Set up meeting with Robert after we have YAML conversion to the new schema so we can discuss - rendering requirements +- Fix OPS rendering problems (requires specific changes in PlatyPS and OPS) After the initial release, we should look at new features and consider whether we fork the tool to a new no-legacy feature set or try to maintain compatibility going forward (ala PowerShellGet 3.0). @@ -69,13 +67,13 @@ Non-goals: The proposal is to update the functionality and schema of PlayPS to improve the module owners experience building and updating Help. -### Help file schema +### Schema for cmdlet reference The following sections outline schema changes for the Help file. | Heading | Level | Required? | Count | Description | | ------------------ | ----- | --------- | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Title | H1 | Y | 1 | - Add reflection of cmdlet platform/alias based on platform
- Could do as Yaml block with Windows: macOS: Linux: (See block below table) | +| Title | H1 | Y | 1 | - No changes | | Synopsis | H2 | Y | 1 | - No changes | | Aliases | H2 | Y | 1 | - New header to support documentation for cmdlet aliases | | Syntax | H2 | Y | 1 | - No changes | @@ -86,79 +84,161 @@ The following sections outline schema changes for the Help file. | Parameters | H2 | Y | 1 | - Parameters Should be sorted Alpha. Currently PlatyPS has a switch to force Alpha versus enumerated. The default is off, please change to On. | | Parameter | H3 | Y | 1-N | - Yaml block should include:
- Parameter Set Name
- AcceptedValues - Should display enumerated values of parameter (like ValidateSet)
- ConfirmImpact - Impact severity should be reflected and displayed to inform defaults for -Confirm | | Common Parameters | H3 | Y | 1 | - Change the fwlink to remove local and version | -| Inputs | H2 | Y | 1 | - Add cross reference link to the API reference for the input/output object type
- [xref link docs](https://review.docs.microsoft.com/en-us/help/contribute/links-how-to?branch=master#xref-cross-reference-links) | +| Inputs | H2 | Y | 1 | - Add cross reference link to the API reference for the input/output object type
- [xref link docs][06] | | Input type | H3 | N | 0-N | | -| Outputs | H2 | Y | 1 | - Add cross reference link to the API reference for the input/output object type
- [xref link docs](https://review.docs.microsoft.com/en-us/help/contribute/links-how-to?branch=master#xref-cross-reference-links) | +| Outputs | H2 | Y | 1 | - Add cross reference link to the API reference for the input/output object type
- [xref link docs][06] | | Output type | H3 | N | 0-N | | | Notes | H2 | N | 1 | Mandatory for schema but not rendered by OPS if empty | | Related links | H3 | Y | 1 | - Link list should use bullets
- PlatyPS needs to support bullets
- Should support Text (prose), not just links | -Structure of YAML for parameters +#### Updated YAML structure for parameters +The following example shows the markdown for the Yaml metadata of a parameter. The Yaml block +contains new metadata items. + +~~~markdown ```yaml -Type: System.String[] -Parameter Sets: PSetName1, PSetName2, PSetName3 +Type: System.Management.Automation.ScopedItemOptions +Parameter Sets: (All) Aliases: - -Required: True (PSetName1, PSetName2) False (PSetName3) -Position: 0 +Required: False +Position: Named Default value: None -Accept pipeline input: True (ByPropertyName, ByValue) -Accept wildcard characters: True -DontShow: True +Accept pipeline input: ByValue (False), ByName (False) +Accept wildcard characters: False +Dynamic: True +Providers: Alias, Function +Values from remaining args: False +Do not show: False +Release status: Feature Preview ``` +~~~ + +New metadata + +- `Dynamic` + - Type: boolean + - Required +- `Providers` + - Type: string containing one or more provider names (comma-separated) + - Optional - expected when `Dynamic` is true +- `Values from remaining args` + - Type: boolean + - Required +- `Do not show` + - Type: boolean + - Required +- `Release status` + - Type: string representation of one enum value from: + - 'Preview', 'Feature Preview', 'Experimental', 'Deprecated' + - Optional + +The OPS build pipeline doesn't need to validate these values. Any validation should be done by +PlatyPS. + +### Schema updates for cmdlet frontmatter + +#### Cmdlet alias metadata + +Have a way to document aliases for the cmdlet. Today we only document aliases for parameters. This +is difficult to discover, so don't need `*-MarkdownHelp` cmdlets to create it but the schema needs +to support it. The author can add the information to the YAML frontmatter. For example: -#### Schema feature requests +```yaml +aliases: + all: [dir, gci] + windows: [ls] + macOS: + linux: +``` -1. Have a way to document aliases for the cmdlet. Today we only document aliases for parameters. - This is difficult to discover, so don't need `*-MarkdownHelp` cmdlets to create it but the schema - needs to support it. The author can add the information to the YAML frontmatter. For example: +Add new H2 for documenting aliases. - ```yaml - aliases: - all: [dir, gci] - windows: [ls] - macOS: - linux: - ``` +```markdown +## ALIASES - Add new H2 for documenting aliases. +PowerShell includes the following aliases for `Get-ChildItem`: - ```markdown - ## ALIASES +- All platforms: `dir`, `gci` +- Windows: `ls` +``` - PowerShell includes the following aliases for `Get-ChildItem`: +See [alias-prototype][02] for a more complete example. - - All platforms: `dir`, `gci` - - Windows: `ls` - ``` +> [!NOTE] +> The `aliases` metadata is optional. The information will be added by the documentation author. The +> ALIASES H2 section is optional and will be added by the documentation author as necessary. The +> reference pipeline shouldn't try to validate this content or metadata values. The reference +> pipeline should add all aliases to the `displayname` property of the Yaml TOC entry for the +> cmdlet. For more information about the `displayname` property, see the [TOC docs][07]. - See [alias-prototype](alias-prototype.md) for an example. +See [Issue #585][04]. - > [!NOTE] - > Since the XSD for MAML is fixed we cannot support the new H2 section in the conversion to MAML. - > Instead we will keep the H2 in the markdown source and in the conversion to YAML. But we need - > to special case the conversion to MAML. The H2 Aliases section can be prepended to the NOTES - > section as a `` item. This means the information will appear in the NOTES section - > of `Get-Help` output. +#### Cmdlet platform availability - See [Issue #585](https://github.com/PowerShell/platyPS/issues/585). +The purpose of this is to represent the availability of the cmdlet for a platform (win/mac/linux). +Could be one or more. PlatyPS could default to Windows when creating the markdown. The value should +be edited by the author to ensure accuracy. -1. Have a some schema format for representing the availability of the cmdlet for a platform - (win/mac/linux). Could be one or more. Default to Windows but editable by the author. +```yaml +- platforms: [win, macOS, linux] +``` - ```yaml - - platforms: win, macOS, linux - ``` +- `platforms` + - Type: string array containing one or more platform names (win, macOS, linux) + - Required -### Formatting note +The reference build pipeline should enforce the requirement but doesn't need to use the values -- General - - Would like PlatyPS to add a line break after each Markdown block - - Example - Headers, Code blocks, Lists - - Bug: `Get-Help`: Requires that the first line of text be immediately following Synopsis header +#### Cmdlet release status metadata + +The purpose of this metadata is to represent the release status of the cmdlet. The value is not +required if the cmdlet is GA. This metadata will be added by the author as necessary. + +```yaml +release: + status : Preview, Feature Preview, Experimental, Deprecated + message : Text of a banner message. +``` -### About_ file schema +- `release` + - Type: string representation of one enum value from: + - 'Preview', 'Feature Preview', 'Experimental', 'Deprecated' + - Optional +- `status` + - Type: string representation of one enum value from: + - 'Preview' - used for cmdlets that are in preview modules + - 'Feature Preview' - used for cmdlets that require Feature flags to be enabled to use + - 'Experimental' - used for cmdlets that are enabled by a PowerShell experimental feature + - 'Deprecated' - used for cmdlet that will be unsupported after a certain date are removed in a + future release + - Required +- `message` + - Type: string - text of an alert message to be displayed in the documentation + - The message should be a single sentence or short paragraph. Include end of support dates if + applicable. + - Required + +The reference build pipeline will use: + +- the `status` to select the badge displayed for the status. +- the `message` to render an alert box on the page containing the message + +Matt Trilby-Bassett has some [Figma designs][08] showing the badge and alert box. + +### Schema for Module file frontmatter + +The `Module.md` file is the landing page for a module and is used during conversion to MAML. The +frontmatter for this file will also include the `release` metadata for non-GA modules. + +See the [release status metadata][01] described above. + +The reference build pipeline will use: + +- the `status` to select the badge displayed for the status. +- the `message` to render an alert box on the page containing the message + +### Schema for About_ files The following sections outline schema changes for the About_ file. @@ -173,14 +253,21 @@ General notes - Should be rendered as plain text compatible with `Get-Help` - `Get-Help` bug:Synopsis -- [Get-Help bug](https://github.com/PowerShell/PowerShell/issues/9208) +- [Get-Help bug][05] - Add switch to provide Cabs or Zips. Default: cabs - Add switch to include markdown Default: off - About_ schema does not say anything about line wrapping etc. - If left as text files, then wrap at 80 columns. - - But if converted to schema-based line limit is not a problem (for the future). Still a problem + - But if converted to schema-based line limit isn't a problem (for the future). Still a problem for previous versions. +### PlatyPS formatting changes + +- General + - Would like PlatyPS to add a line break after each Markdown block + - Example - Headers, Code blocks, Lists + - Bug: `Get-Help`: Requires that the first line of text be immediately following Synopsis header + ## PlatyPS Cmdlets and Parameters PlatyPS includes a set of cmdlets with parameters. @@ -342,4 +429,14 @@ TODO ## Issues for this milestone -[2.0-consider](https://github.com/PowerShell/platyPS/issues?q=is%3Aopen+is%3Aissue+milestone%3A2.0-consider) +[2.0-consider][03] + + +[01]: #cmdlet-release-status-metadata +[02]: alias-prototype.md +[03]: https://github.com/PowerShell/platyPS/issues?q=is%3Aopen+is%3Aissue+milestone%3A2.0-consider +[04]: https://github.com/PowerShell/platyPS/issues/585 +[05]: https://github.com/PowerShell/PowerShell/issues/9208 +[06]: https://review.docs.microsoft.com/en-us/help/contribute/links-how-to?branch=master#xref-cross-reference-links +[07]: https://review.learn.microsoft.com/en-us/help/platform/navigation-toc-overview?branch=main#yaml-toc-format +[08]: https://www.figma.com/file/EP3wMMct92SqHwvWcorb9O/%5BDiscovery%5D-Reference-Development-Status-Information?node-id=897%3A3314&t=zy1ygL7Gh5ChSyh1-0 From d386d945f44bcbd22ec55d48d14d71b0a1b3db3e Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Thu, 23 Mar 2023 15:12:45 -0500 Subject: [PATCH 18/27] Update schema specs --- specs/platyps_2.0_about_schema.md | 22 +++ specs/platyps_2.0_cmdlets.md | 158 ++++++++++++++++++++++ specs/platyps_2.0_update.md | 213 +++--------------------------- 3 files changed, 201 insertions(+), 192 deletions(-) create mode 100644 specs/platyps_2.0_about_schema.md create mode 100644 specs/platyps_2.0_cmdlets.md diff --git a/specs/platyps_2.0_about_schema.md b/specs/platyps_2.0_about_schema.md new file mode 100644 index 00000000..6d16b18e --- /dev/null +++ b/specs/platyps_2.0_about_schema.md @@ -0,0 +1,22 @@ +# Schema for About_ files + +The following sections outline schema changes for the About_ file. + +| Heading | Level | Required? | Count | Description | +| ----------------- | ----- | --------- | ----- | ------------------------------------------------------------------------------------------------------------------------- | +| Title | H1 | Y | 1 | - Title should be Sentence Case - About Topic
- Title meta data 'about_' should match the file basename | +| Short Description | H2 | Y | 1 | - Should be Sentence Case | +| Long Description | H2 | Y | 1 | - Should be Sentence case
- Should allow multiple Long description subtopics
- Should support subtopics at H3 or H2 | +| See Also | H2 | Y | 1 | - This is required but may be empty | + +General notes + +- Should be rendered as plain text compatible with `Get-Help` +- `Get-Help` bug:Synopsis +- [Get-Help bug][05] +- Add switch to provide Cabs or Zips. Default: cabs +- Add switch to include markdown Default: off +- About_ schema does not say anything about line wrapping etc. + - If left as text files, then wrap at 80 columns. + - But if converted to schema-based line limit isn't a problem (for the future). Still a problem + for previous versions. diff --git a/specs/platyps_2.0_cmdlets.md b/specs/platyps_2.0_cmdlets.md new file mode 100644 index 00000000..33aeb0d2 --- /dev/null +++ b/specs/platyps_2.0_cmdlets.md @@ -0,0 +1,158 @@ +## PlatyPS Cmdlets and Parameters + +PlatyPS includes a set of cmdlets with parameters. + +The following section is a review of the cmdlets for changes to the parameters and their defaults. +We need to decide to what cmdlets and features to keep. We should make a list breaking changes for +documentation. + +In case of breaking changes, do we need a legacy mode? + +- We don't know until we see what all the breaking changes are +- If we make changes that require changes to Get-Help we will need something that targets a older + versions PowerShell. + +#### Get-HelpPreview + +| ParamName | DefaultValue | Description | +| ---------------------- | ------------ | ------------------------------------------------------------------------------------------ | +| Path | None | Specifies an array of paths of MAML external help files | +| ConvertNotesToList | False | Indicates that this cmldet formats multiple paragraph items in the NOTES section as single | +| ConvertDoubleDashLists | False | Indicates that this cmldet converts double-hyphen list bullets into single-hyphen bullets | + +#### Get-MarkdownMetadata + +| ParamName | DefaultValue | Description | +| --------- | ------------ | -------------------------------------------------------- | +| Path | None | Specifies an array of paths of markdown files or folders | +| Markdown | None | Specifies a string that contains markdown formatted text | + +#### Merge-MarkdownHelp + +| ParamName | DefaultValue | Description | +| ----------------------- | ---------------- | ------------------------------------------------------------------------------------- | +| Encoding | UTF8 without BOM | Specifies the character encoding for your external help file. Specify a System.Text.E | +| ExplicitApplicableIfAll | False | Always write out full list of applicable tags. By default cmdlets and parameters that | +| Force | False | Indicates that this cmdlet overwrites an existing file that has the same name | +| MergeMarker | '!!! ' | String to be used as a merge text indicator. Applicable tag list would be included | +| OutputPath | None | Specifies the path of the folder where this cmdlet creates the combined markdown help | +| Path | None | Specifies an array of paths of markdown files or folders. This cmdlet creates | + +#### New-ExternalHelp + +| ParamName | DefaultValue | Description | +| ------------- | ---------------- | ----------------------------------------------------------------------------------------------- | +| OutputPath | None | Specifies the path of a folder where this cmdlet saves your external help file. The folder name | +| Encoding | UTF8 without BOM | Specifies the character encoding for your external help file. Specify a System.Text.Encoding | +| Force | False | Indicates that this cmdlet overwrites an existing file that has the same name | +| Path | None | Specifies an array of paths of markdown files or folders. This cmdlet creates external help | +| ApplicableTag | None | Specify array of tags to use as a filter. If cmdlet has `applicable` in the yaml metadata | +| MaxAboutWidth | 80 | Specifies the maximimum line length when generating "about" help text files. | +| ErrorLogFile | None | The path where this cmdlet will save formatted results log file | +| ShowProgress | False | Display progress bars under parsing existing markdown files | + +#### New-ExternalHelpCab + +| ParamName | DefaultValue | Description | +| -------------------- | ------------ | ------------------------------------------------------------------------------------------- | +| CabFilesFolder | None | Specifies the folder that contains the help content that this cmdlet packages into a .cab | +| LandingPagePath | None | Specifies the full path of the Module Markdown file that contains all the metadata required | +| OutputFolder | None | Specifies the location of the .cab file and helpinfo.xml file that this cmdlet creates | +| IncrementHelpVersion | False | Automatically increment the help version in the module markdown file | + +#### New-MarkdownAboutHelp + +| ParamName | DefaultValue | Description | +| ------------ | ------------ | ------------------------------------------ | +| AboutName | None | The name of the about topic | +| OutputFolder | None | The directory to create the about topic in | + +#### New-MarkdownHelp + +| ParamName | DefaultValue | Description | +| ---------------------- | ---------------- | --------------------------------------------------------------------------------------- | +| Command | None | Specifies the name of a command in your current session. This can be any command | +| Encoding | UTF8 without BOM | Specifies the character encoding for your markdown help files | +| Force | False | Indicates that this cmdlet overwrites existing files that have the same names | +| FwLink | None | Specifies the forward link for the module page. This value is required for .cab | +| HelpVersion | None | Specifies the version of your help. This value is required for .cab file creation | +| Locale | None | Specifies the locale of your help. This value is required for .cab file creation | +| MamlFile | None | Specifies an array of paths path of MAML .xml help files | +| Metadata | None | Specifies metadata that this cmdlet includes in the help markdown files as a hash table | +| Module | None | Specifies an array of names of modules for which this cmdlet creates help in markdown | +| ModuleGuid | None | Specifies the GUID of the module of your help. This value is required for .cab file | +| ModuleName | None | Specifies the name of the module of your help. This value is required for .cab file | +| NoMetadata | False | Indicates that this cmdlet does not write any metadata in the generated markdown | +| OnlineVersionUrl | None | Specifies the URL where the updatable help function downloads updated help | +| OutputFolder | None | Specifies the path of the folder where this cmdlet creates the markdown help files | +| WithModulePage | False | Indicates that this cmdlet creates a module page in the output folder | +| ConvertNotesToList | False | Indicates that this cmldet formats multiple paragraph items in the NOTES section | +| ConvertDoubleDashLists | False | Indicates that this cmldet converts double-hyphen list bullets into single-hyphen | +| AlphabeticParamsOrder | False | Order parameters alphabetically by name in PARAMETERS section. There are 5 exceptions | +| UseFullTypeName | False | Indicates that the target document will use a full type name instead of a short name | +| Session | None | Provides support for remote commands. Pass the session that you used to create | +| ModulePagePath | None | When WithModule parameter is used by default it puts .md file in same location as all | +| ExcludeDontShow | False | Exclude the parameters marked with `DontShow` in the parameter attribute from the help | + +#### New-YamlHelp + +| ParamName | DefaultValue | Description | +| ------------ | ------------ | --------------------------------------------------------------------------------------------------- | +| Encoding | None | Specifies the character encoding for your external help file. Specify a System.Text.Encoding object | +| Force | False | Indicates that this cmdlet overwrites an existing file that has the same name | +| Path | None | Specifies an array of paths of markdown files or folders | +| OutputFolder | None | Specifies the folder to create the YAML files | + +#### Update-MarkdownHelp + +| ParamName | DefaultValue | Description | +| --------------------- | ---------------- | ------------------------------------------------------------------------------------ | +| Encoding | UTF8 without BOM | Specifies the character encoding for your markdown help files | +| LogAppend | False | Indicates that this cmdlet appends information to the log instead overwriting it | +| LogPath | None | Specifies a file path for log information. The cmdlet writes the VERBOSE stream | +| Path | None | Specifies an array of paths of markdown files and folders to update | +| AlphabeticParamsOrder | False | Order parameters alphabetically by name in PARAMETERS section | +| UseFullTypeName | False | Indicates that the target document will use a full type name instead of a short name | +| Session | None | Provides support for remote commands. Pass the session that you used to create | +| UpdateInputOutput | False | Refreshes the Input and Output section to reflect the current state of the cmdlet | +| Force | False | Remove help files that no longer exists within sessions | +| ExcludeDontShow | False | Exclude the parameters marked with `DontShow` in the parameter attribute | + +#### Update-MarkdownHelpModule + +| ParamName | DefaultValue | Description | +| --------------------- | ---------------- | -------------------------------------------------------------------------------------- | +| Encoding | UTF8 without BOM | Specifies the character encoding for your markdown help files | +| LogAppend | False | Indicates that this cmdlet appends information to the log instead overwriting | +| LogPath | None | Specifies a file path for log information. The cmdlet writes the VERBOSE stream | +| Path | None | Specifies an array of paths of markdown folders to update. The folder must contain | +| RefreshModulePage | False | Update module page when updating the help module | +| AlphabeticParamsOrder | False | Order parameters alphabetically by name in PARAMETERS section | +| Session | None | Provides support for remote commands. Pass the session that you used to create | +| UseFullTypeName | False | Indicates that the target document will use a full type name instead of a short name | +| UpdateInputOutput | False | Refreshes the Input and Output sections to reflect the current state of the cmdlet | +| ModulePagePath | None | When -RefreshModulePage is used by default it puts .md file in same location | +| Force | False | Remove help files that no longer exists within sessions | +| ExcludeDontShow | False | Exclude the parameters marked with `DontShow` in the parameter attribute from the help | + +## Cmdlet Feature requests + +1. I was wondering if we should default to zips instead, one package for both platforms. Cabs as + legacy for < 5.1 content. We can fix PS 7.2 to look for zip first and fallback to cab. Add as + question in spec — This should be a switch - cab, zip or both. + +1. Need to know about Merge-MarkdownHelp which uses `applicable:` yaml syntax for version. + `applicable:` should be mentioned in the schema. — this creates tags…for linux/windows + parameters. Exchange uses the `applicable:` feature heavily. Need to maintain support for them. + +1. Need way to increment the help version number of the CAB files + + - Could be automatic in every build? + - Could be scheduled? + - Could be a workflow step (scripted) done by the author + - Need to figure out limits of version number fields + - Need rules for when to increment major, minor, subminor, etc. (Semvar?) + +### List of things that break with PS5.1 or Exchange + +TODO diff --git a/specs/platyps_2.0_update.md b/specs/platyps_2.0_update.md index 1095a628..72ab75bb 100644 --- a/specs/platyps_2.0_update.md +++ b/specs/platyps_2.0_update.md @@ -130,11 +130,16 @@ New metadata - Required - `Release status` - Type: string representation of one enum value from: - - 'Preview', 'Feature Preview', 'Experimental', 'Deprecated' - - Optional + - 'Preview' - typically not used for parameters + - 'Feature Preview' - typically not used for parameters + - 'Experimental' - used for parameters that are enabled by a PowerShell experimental feature + - 'Deprecated' - used for cmdlet that will be unsupported after a certain date are removed in a + future release + - Null value - indicates the parameter is GA (currently supported) + - Optional - the value can be null or the key-value pair omitted -The OPS build pipeline doesn't need to validate these values. Any validation should be done by -PlatyPS. +The OPS build pipeline should validate that the values match the type. `Release status` should only +be rendered on the page if the key has a value (not null). ### Schema updates for cmdlet frontmatter @@ -192,9 +197,12 @@ The reference build pipeline should enforce the requirement but doesn't need to #### Cmdlet release status metadata -The purpose of this metadata is to represent the release status of the cmdlet. The value is not +The purpose of this metadata is to represent the release status of the cmdlet. The value isn't required if the cmdlet is GA. This metadata will be added by the author as necessary. +PlatyPS should create the metadata as placeholders in the frontmatter. The author should delete the +keys or update the values as appropriate. + ```yaml release: status : Preview, Feature Preview, Experimental, Deprecated @@ -207,8 +215,10 @@ release: - Optional - `status` - Type: string representation of one enum value from: - - 'Preview' - used for cmdlets that are in preview modules - - 'Feature Preview' - used for cmdlets that require Feature flags to be enabled to use + - 'Preview' - used for cmdlets from preview modules where the version is 0.x.y with no + Prerelease label + - 'Feature Preview' - used for cmdlets from feature preview modules where the version is 1.x.y + or higher and has a Prerelease label - 'Experimental' - used for cmdlets that are enabled by a PowerShell experimental feature - 'Deprecated' - used for cmdlet that will be unsupported after a certain date are removed in a future release @@ -219,10 +229,11 @@ release: applicable. - Required -The reference build pipeline will use: +The reference build pipeline should do the following: -- the `status` to select the badge displayed for the status. -- the `message` to render an alert box on the page containing the message +- Use the `status` to select the badge displayed for the status. +- Use the `message` to render an alert box on the page containing the message +- Validate that the values match the types. Matt Trilby-Bassett has some [Figma designs][08] showing the badge and alert box. @@ -238,29 +249,6 @@ The reference build pipeline will use: - the `status` to select the badge displayed for the status. - the `message` to render an alert box on the page containing the message -### Schema for About_ files - -The following sections outline schema changes for the About_ file. - -| Heading | Level | Required? | Count | Description | -| ----------------- | ----- | --------- | ----- | ------------------------------------------------------------------------------------------------------------------------- | -| Title | H1 | Y | 1 | - Title should be Sentence Case - About Topic
- Title meta data 'about_' should match the file basename | -| Short Description | H2 | Y | 1 | - Should be Sentence Case | -| Long Description | H2 | Y | 1 | - Should be Sentence case
- Should allow multiple Long description subtopics
- Should support subtopics at H3 or H2 | -| See Also | H2 | Y | 1 | - This is required but may be empty | - -General notes - -- Should be rendered as plain text compatible with `Get-Help` -- `Get-Help` bug:Synopsis -- [Get-Help bug][05] -- Add switch to provide Cabs or Zips. Default: cabs -- Add switch to include markdown Default: off -- About_ schema does not say anything about line wrapping etc. - - If left as text files, then wrap at 80 columns. - - But if converted to schema-based line limit isn't a problem (for the future). Still a problem - for previous versions. - ### PlatyPS formatting changes - General @@ -268,165 +256,6 @@ General notes - Example - Headers, Code blocks, Lists - Bug: `Get-Help`: Requires that the first line of text be immediately following Synopsis header -## PlatyPS Cmdlets and Parameters - -PlatyPS includes a set of cmdlets with parameters. - -The following section is a review of the cmdlets for changes to the parameters and their defaults. -We need to decide to what cmdlets and features to keep. We should make a list breaking changes for -documentation. - -In case of breaking changes, do we need a legacy mode? - -- We don't know until we see what all the breaking changes are -- If we make changes that require changes to Get-Help we will need something that targets a older - versions PowerShell. - -#### Get-HelpPreview - -| ParamName | DefaultValue | Description | -| ---------------------- | ------------ | ------------------------------------------------------------------------------------------ | -| Path | None | Specifies an array of paths of MAML external help files | -| ConvertNotesToList | False | Indicates that this cmldet formats multiple paragraph items in the NOTES section as single | -| ConvertDoubleDashLists | False | Indicates that this cmldet converts double-hyphen list bullets into single-hyphen bullets | - -#### Get-MarkdownMetadata - -| ParamName | DefaultValue | Description | -| --------- | ------------ | -------------------------------------------------------- | -| Path | None | Specifies an array of paths of markdown files or folders | -| Markdown | None | Specifies a string that contains markdown formatted text | - -#### Merge-MarkdownHelp - -| ParamName | DefaultValue | Description | -| ----------------------- | ---------------- | ------------------------------------------------------------------------------------- | -| Encoding | UTF8 without BOM | Specifies the character encoding for your external help file. Specify a System.Text.E | -| ExplicitApplicableIfAll | False | Always write out full list of applicable tags. By default cmdlets and parameters that | -| Force | False | Indicates that this cmdlet overwrites an existing file that has the same name | -| MergeMarker | '!!! ' | String to be used as a merge text indicator. Applicable tag list would be included | -| OutputPath | None | Specifies the path of the folder where this cmdlet creates the combined markdown help | -| Path | None | Specifies an array of paths of markdown files or folders. This cmdlet creates | - -#### New-ExternalHelp - -| ParamName | DefaultValue | Description | -| ------------- | ---------------- | ----------------------------------------------------------------------------------------------- | -| OutputPath | None | Specifies the path of a folder where this cmdlet saves your external help file. The folder name | -| Encoding | UTF8 without BOM | Specifies the character encoding for your external help file. Specify a System.Text.Encoding | -| Force | False | Indicates that this cmdlet overwrites an existing file that has the same name | -| Path | None | Specifies an array of paths of markdown files or folders. This cmdlet creates external help | -| ApplicableTag | None | Specify array of tags to use as a filter. If cmdlet has `applicable` in the yaml metadata | -| MaxAboutWidth | 80 | Specifies the maximimum line length when generating "about" help text files. | -| ErrorLogFile | None | The path where this cmdlet will save formatted results log file | -| ShowProgress | False | Display progress bars under parsing existing markdown files | - -#### New-ExternalHelpCab - -| ParamName | DefaultValue | Description | -| -------------------- | ------------ | ------------------------------------------------------------------------------------------- | -| CabFilesFolder | None | Specifies the folder that contains the help content that this cmdlet packages into a .cab | -| LandingPagePath | None | Specifies the full path of the Module Markdown file that contains all the metadata required | -| OutputFolder | None | Specifies the location of the .cab file and helpinfo.xml file that this cmdlet creates | -| IncrementHelpVersion | False | Automatically increment the help version in the module markdown file | - -#### New-MarkdownAboutHelp - -| ParamName | DefaultValue | Description | -| ------------ | ------------ | ------------------------------------------ | -| AboutName | None | The name of the about topic | -| OutputFolder | None | The directory to create the about topic in | - -#### New-MarkdownHelp - -| ParamName | DefaultValue | Description | -| ---------------------- | ---------------- | --------------------------------------------------------------------------------------- | -| Command | None | Specifies the name of a command in your current session. This can be any command | -| Encoding | UTF8 without BOM | Specifies the character encoding for your markdown help files | -| Force | False | Indicates that this cmdlet overwrites existing files that have the same names | -| FwLink | None | Specifies the forward link for the module page. This value is required for .cab | -| HelpVersion | None | Specifies the version of your help. This value is required for .cab file creation | -| Locale | None | Specifies the locale of your help. This value is required for .cab file creation | -| MamlFile | None | Specifies an array of paths path of MAML .xml help files | -| Metadata | None | Specifies metadata that this cmdlet includes in the help markdown files as a hash table | -| Module | None | Specifies an array of names of modules for which this cmdlet creates help in markdown | -| ModuleGuid | None | Specifies the GUID of the module of your help. This value is required for .cab file | -| ModuleName | None | Specifies the name of the module of your help. This value is required for .cab file | -| NoMetadata | False | Indicates that this cmdlet does not write any metadata in the generated markdown | -| OnlineVersionUrl | None | Specifies the URL where the updatable help function downloads updated help | -| OutputFolder | None | Specifies the path of the folder where this cmdlet creates the markdown help files | -| WithModulePage | False | Indicates that this cmdlet creates a module page in the output folder | -| ConvertNotesToList | False | Indicates that this cmldet formats multiple paragraph items in the NOTES section | -| ConvertDoubleDashLists | False | Indicates that this cmldet converts double-hyphen list bullets into single-hyphen | -| AlphabeticParamsOrder | False | Order parameters alphabetically by name in PARAMETERS section. There are 5 exceptions | -| UseFullTypeName | False | Indicates that the target document will use a full type name instead of a short name | -| Session | None | Provides support for remote commands. Pass the session that you used to create | -| ModulePagePath | None | When WithModule parameter is used by default it puts .md file in same location as all | -| ExcludeDontShow | False | Exclude the parameters marked with `DontShow` in the parameter attribute from the help | - -#### New-YamlHelp - -| ParamName | DefaultValue | Description | -| ------------ | ------------ | --------------------------------------------------------------------------------------------------- | -| Encoding | None | Specifies the character encoding for your external help file. Specify a System.Text.Encoding object | -| Force | False | Indicates that this cmdlet overwrites an existing file that has the same name | -| Path | None | Specifies an array of paths of markdown files or folders | -| OutputFolder | None | Specifies the folder to create the YAML files | - -#### Update-MarkdownHelp - -| ParamName | DefaultValue | Description | -| --------------------- | ---------------- | ------------------------------------------------------------------------------------ | -| Encoding | UTF8 without BOM | Specifies the character encoding for your markdown help files | -| LogAppend | False | Indicates that this cmdlet appends information to the log instead overwriting it | -| LogPath | None | Specifies a file path for log information. The cmdlet writes the VERBOSE stream | -| Path | None | Specifies an array of paths of markdown files and folders to update | -| AlphabeticParamsOrder | False | Order parameters alphabetically by name in PARAMETERS section | -| UseFullTypeName | False | Indicates that the target document will use a full type name instead of a short name | -| Session | None | Provides support for remote commands. Pass the session that you used to create | -| UpdateInputOutput | False | Refreshes the Input and Output section to reflect the current state of the cmdlet | -| Force | False | Remove help files that no longer exists within sessions | -| ExcludeDontShow | False | Exclude the parameters marked with `DontShow` in the parameter attribute | - -#### Update-MarkdownHelpModule - -| ParamName | DefaultValue | Description | -| --------------------- | ---------------- | -------------------------------------------------------------------------------------- | -| Encoding | UTF8 without BOM | Specifies the character encoding for your markdown help files | -| LogAppend | False | Indicates that this cmdlet appends information to the log instead overwriting | -| LogPath | None | Specifies a file path for log information. The cmdlet writes the VERBOSE stream | -| Path | None | Specifies an array of paths of markdown folders to update. The folder must contain | -| RefreshModulePage | False | Update module page when updating the help module | -| AlphabeticParamsOrder | False | Order parameters alphabetically by name in PARAMETERS section | -| Session | None | Provides support for remote commands. Pass the session that you used to create | -| UseFullTypeName | False | Indicates that the target document will use a full type name instead of a short name | -| UpdateInputOutput | False | Refreshes the Input and Output sections to reflect the current state of the cmdlet | -| ModulePagePath | None | When -RefreshModulePage is used by default it puts .md file in same location | -| Force | False | Remove help files that no longer exists within sessions | -| ExcludeDontShow | False | Exclude the parameters marked with `DontShow` in the parameter attribute from the help | - -## Cmdlet Feature requests - -1. I was wondering if we should default to zips instead, one package for both platforms. Cabs as - legacy for < 5.1 content. We can fix PS 7.2 to look for zip first and fallback to cab. Add as - question in spec — This should be a switch - cab, zip or both. - -1. Need to know about Merge-MarkdownHelp which uses `applicable:` yaml syntax for version. - `applicable:` should be mentioned in the schema. — this creates tags…for linux/windows - parameters. Exchange uses the `applicable:` feature heavily. Need to maintain support for them. - -1. Need way to increment the help version number of the CAB files - - - Could be automatic in every build? - - Could be scheduled? - - Could be a workflow step (scripted) done by the author - - Need to figure out limits of version number fields - - Need rules for when to increment major, minor, subminor, etc. (Semvar?) - -### List of things that break with PS5.1 or Exchange - -TODO - ## Issues for this milestone [2.0-consider][03] From 28878a83b8c92e9a44f3fc14d455c10cb7ec4078 Mon Sep 17 00:00:00 2001 From: Davide Dunne Sanchez <111002142+DavideDunne@users.noreply.github.com> Date: Fri, 3 Nov 2023 11:55:18 -0600 Subject: [PATCH 19/27] Update README.md (#606) Link to module gallery page instead of PS Gallery homepage --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index dbb786c1..5f7b2063 100644 --- a/README.md +++ b/README.md @@ -37,7 +37,7 @@ There is slight preference toward number 1 (markdown as the source). ## Quick start -* Install platyPS module from the [PowerShell Gallery](https://powershellgallery.com): +* Install platyPS module from the [PowerShell Gallery](https://www.powershellgallery.com/packages/platyPS): ```powershell Install-Module -Name platyPS -Scope CurrentUser From 837945f5ff8c230c43597967d57feeb80ad33529 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Tue, 5 Dec 2023 15:17:58 -0600 Subject: [PATCH 20/27] Update V2 specs to include more parameter metadata --- specs/alias-prototype.md | 8 ++------ specs/platyps_2.0_update.md | 28 +++++++++++++++++++++++----- 2 files changed, 25 insertions(+), 11 deletions(-) diff --git a/specs/alias-prototype.md b/specs/alias-prototype.md index 790df72c..9da66a77 100644 --- a/specs/alias-prototype.md +++ b/specs/alias-prototype.md @@ -2,15 +2,11 @@ external help file: Microsoft.PowerShell.Commands.Management.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Management -ms.date: 03/27/2020 +ms.date: 12/05/2023 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.management/get-childitem?view=powershell-7.2&WT.mc_id=ps-gethelp schema: 2.0.0 title: Get-ChildItem -alias: - all: [dir, gci] - windows: [ls] - macos: - linux: +alias: [dir, gci, ls] --- # Get-ChildItem diff --git a/specs/platyps_2.0_update.md b/specs/platyps_2.0_update.md index 72ab75bb..98ff28d3 100644 --- a/specs/platyps_2.0_update.md +++ b/specs/platyps_2.0_update.md @@ -110,24 +110,46 @@ Dynamic: True Providers: Alias, Function Values from remaining args: False Do not show: False +Is credential: False +Is obsolete: False Release status: Feature Preview ``` ~~~ +Notes + +- Values for most items should be obtained by reflection. +- Provider information will have to be tested individually based on the currently loaded providers. +- The `Default value` should be obtained by reflection, if possible. + - The default value for **SwitchParameter** types should be `False`. +- If possible, the `Parameter sets` and `Providers` values should be simplified to show `(All)` when + the value is the same for all parameter sets or providers. + New metadata - `Dynamic` - Type: boolean + - Obtained by reflection of parameter attributes - Required - `Providers` - Type: string containing one or more provider names (comma-separated) - Optional - expected when `Dynamic` is true - `Values from remaining args` - Type: boolean + - Obtained by reflection of parameter attributes - Required - `Do not show` - Type: boolean + - Obtained by reflection of parameter attributes - Required +- `Is credential` + - Type: boolean + - Obtained by reflection of parameter attributes + - Required +- `Is obsolete` + - Type: boolean + - Obtained by reflection of parameter attributes + - Required - `Release status` - Type: string representation of one enum value from: - 'Preview' - typically not used for parameters @@ -150,11 +172,7 @@ is difficult to discover, so don't need `*-MarkdownHelp` cmdlets to create it bu to support it. The author can add the information to the YAML frontmatter. For example: ```yaml -aliases: - all: [dir, gci] - windows: [ls] - macOS: - linux: +aliases: [dir, gci, ls] ``` Add new H2 for documenting aliases. From 21d33fcba8dddd42e444e9eb6190741f7634ec03 Mon Sep 17 00:00:00 2001 From: James Truher Date: Tue, 20 Feb 2024 15:51:01 -0800 Subject: [PATCH 21/27] Change v2 schema for parameter. Parameter now contains a collection of parameter sets which will enable tracking a number of attributes on a parameter _and_ parameterset basis. This is because a parameter may be position in one parameter set but not positional in another parameter set. --- specs/PowershellCmdletV2.schema.json | 63 +++++++++++++++++++--------- 1 file changed, 43 insertions(+), 20 deletions(-) diff --git a/specs/PowershellCmdletV2.schema.json b/specs/PowershellCmdletV2.schema.json index ac9626a4..2e9e70c1 100644 --- a/specs/PowershellCmdletV2.schema.json +++ b/specs/PowershellCmdletV2.schema.json @@ -136,7 +136,7 @@ "cmdletParameters": { // naming pending? use only a single word as the name if possible "items": { "additionalProperties": false, - "required": ["name", "description", "type", "position", "parameterValueGroup"], + "required": ["name", "description", "type", "parameterSet"], "properties": { "name": { "type": "string" @@ -146,42 +146,65 @@ "contentType": "markdown", "tags": ["localizable"] }, - "isRequired": { - "type": "boolean" + "type": { + "type": "string", + "contentType": "markdown" + }, + "parameterSet" : { + "items": { + "type": "array", + "minItems": 1, + "additionalProperties": false, + "required": [ "name" ], + "properties": { + "name": { + "type": "string" + }, + "position": { + "type": "string" + }, + "valueByPipeline": { + "type": "boolean" + }, + "valueByPipelineByPropertyName": { + "type": "boolean" + }, + "valueFromRemainingArguments": { + "type": "boolean" + }, + "isRequired": { // mandatory + "type": "boolean" + } + } + } }, - "applicable": { + "applicable": { // ???? "items": { "type": "string" }, "minItems": 1, "type": "array" }, - "type": { - "type": "string", - "contentType": "markdown" - }, "aliases": { - "type": "string" + "type": "array", + "minItems": 1, + "items": { + "type": "string" + } }, - "parameterValueGroup": { + "isDynamic": { + "type": "boolean" + }, + "allowedValues": { // parameterValueGroup "items": { "type": "string" }, "minItems": 1, "type": "array" }, - "parameterSetName": { - "type": "string" - }, - "position": { - "type": "string" - }, "defaultValue": { "type": "string" }, - "pipelineInput": { // change from bool to string, need to change js and template - "type": "string" - }, "acceptWildcardCharacters": { "type": "boolean" }, @@ -194,7 +217,7 @@ "minItems": 1, "type": "array" }, - "commonParameters": { + "commonParameters": { // This implies has cmdlet binding "type": "string", "contentType": "markdown", "tags": ["localizable"] From f9fa12821b6dbacdd16cc486b77787cdc51242fa Mon Sep 17 00:00:00 2001 From: Andy Jordan <2226434+andyleejordan@users.noreply.github.com> Date: Wed, 12 Jun 2024 15:25:15 -0700 Subject: [PATCH 22/27] Update Code of Conduct and Security Policy (#644) Updates the readme, code of conduct and security policy per OSPO request. --- CODE_OF_CONDUCT.md | 10 ++++++++++ README.md | 8 ++++++++ SECURITY.md | 41 +++++++++++++++++++++++++++++++++++++++++ 3 files changed, 59 insertions(+) create mode 100644 CODE_OF_CONDUCT.md create mode 100644 SECURITY.md diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 00000000..686e5e7a --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,10 @@ +# Microsoft Open Source Code of Conduct + +This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). + +Resources: + +- [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/) +- [Microsoft Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) +- Contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with questions or concerns +- Employees can reach out at [aka.ms/opensource/moderation-support](https://aka.ms/opensource/moderation-support) diff --git a/README.md b/README.md index 5f7b2063..f4e0fcc3 100644 --- a/README.md +++ b/README.md @@ -113,3 +113,11 @@ Just pass `-Session $Session` parameter to the platyPS cmdlets and it will do th ## Build For information about building from sources and contributing see [contributing guidelines](CONTRIBUTING.md). + +## Code of Conduct + +Please see our [Code of Conduct](CODE_OF_CONDUCT.md) before participating in this project. + +## Security Policy + +For any security issues, please see our [Security Policy](SECURITY.md). diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 00000000..f941d308 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,41 @@ + + +## Security + +Microsoft takes the security of our software products and services seriously, which includes all source code repositories managed through our GitHub organizations, which include [Microsoft](https://github.com/Microsoft), [Azure](https://github.com/Azure), [DotNet](https://github.com/dotnet), [AspNet](https://github.com/aspnet), [Xamarin](https://github.com/xamarin) and [PowerShell](https://github.com/PowerShell). + +If you believe you have found a security vulnerability in any Microsoft-owned repository that meets [Microsoft's definition of a security vulnerability](https://aka.ms/security.md/definition), please report it to us as described below. + +## Reporting Security Issues + +**Please do not report security vulnerabilities through public GitHub issues.** + +Instead, please report them to the Microsoft Security Response Center (MSRC) at [https://msrc.microsoft.com/create-report](https://aka.ms/security.md/msrc/create-report). + +If you prefer to submit without logging in, send email to [secure@microsoft.com](mailto:secure@microsoft.com). If possible, encrypt your message with our PGP key; please download it from the [Microsoft Security Response Center PGP Key page](https://aka.ms/security.md/msrc/pgp). + +You should receive a response within 24 hours. If for some reason you do not, please follow up via email to ensure we received your original message. Additional information can be found at [microsoft.com/msrc](https://www.microsoft.com/msrc). + +Please include the requested information listed below (as much as you can provide) to help us better understand the nature and scope of the possible issue: + + * Type of issue (e.g. buffer overflow, SQL injection, cross-site scripting, etc.) + * Full paths of source file(s) related to the manifestation of the issue + * The location of the affected source code (tag/branch/commit or direct URL) + * Any special configuration required to reproduce the issue + * Step-by-step instructions to reproduce the issue + * Proof-of-concept or exploit code (if possible) + * Impact of the issue, including how an attacker might exploit the issue + +This information will help us triage your report more quickly. + +If you are reporting for a bug bounty, more complete reports can contribute to a higher bounty award. Please visit our [Microsoft Bug Bounty Program](https://aka.ms/security.md/msrc/bounty) page for more details about our active programs. + +## Preferred Languages + +We prefer all communications to be in English. + +## Policy + +Microsoft follows the principle of [Coordinated Vulnerability Disclosure](https://aka.ms/security.md/cvd). + + From bfbb78ecb8fe7ea9c717185ea680873956b687f7 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Tue, 22 Oct 2024 13:55:24 -0500 Subject: [PATCH 23/27] Reorganizing documentation in preparation for p1 release --- CHANGELOG.md | 15 +- README.md | 134 +++--- .../Compare-CommandHelp.md | 134 ++++++ .../Export-MamlCommandHelp.md | 210 +++++++++ .../Export-MarkdownCommandHelp.md | 279 ++++++++++++ .../Export-MarkdownModuleFile.md | 239 ++++++++++ .../Export-YamlCommandHelp.md | 260 +++++++++++ .../Export-YamlModuleFile.md | 237 ++++++++++ .../Import-MamlHelp.md | 124 ++++++ .../Import-MarkdownCommandHelp.md | 156 +++++++ .../Import-MarkdownModuleFile.md | 138 ++++++ .../Import-YamlCommandHelp.md | 177 ++++++++ .../Import-YamlModuleFile.md | 155 +++++++ .../Measure-PlatyPSMarkdown.md | 153 +++++++ .../Microsoft.PowerShell.PlatyPS.md | 97 ++++ .../New-CommandHelp.md | 124 ++++++ .../New-MarkdownCommandHelp.md | 413 ++++++++++++++++++ .../New-MarkdownModuleFile.md | 332 ++++++++++++++ .../Test-MarkdownCommandHelp.md | 177 ++++++++ .../Update-CommandHelp.md | 177 ++++++++ .../Update-MarkdownCommandHelp.md | 218 +++++++++ .../Update-MarkdownModuleFile.md | 406 +++++++++++++++++ .../platyPS}/Get-HelpPreview.md | 0 .../platyPS}/Get-MarkdownMetadata.md | 0 .../platyPS}/Merge-MarkdownHelp.md | 0 .../platyPS}/New-ExternalHelp.md | 0 .../platyPS}/New-ExternalHelpCab.md | 0 .../platyPS}/New-MarkdownAboutHelp.md | 0 .../platyPS}/New-MarkdownHelp.md | 0 .../platyPS}/New-YamlHelp.md | 0 .../platyPS}/Update-MarkdownHelp.md | 0 .../platyPS}/Update-MarkdownHelpModule.md | 0 .../platyPS}/about_platyPS.md | 0 .../CONTRIBUTING.md | 53 +++ .../specs/PlatyPS-Design-Notes.md | 147 +++++++ .../specs}/PowerShellCmdlet.schema.json | 0 .../specs}/PowershellCmdletV2.schema.json | 0 .../specs}/Schema-Notes.md | 0 .../specs}/alias-prototype.md | 0 .../specs}/platyps_2.0_about_schema.md | 0 .../specs}/platyps_2.0_cmdlets.md | 0 .../specs}/platyps_2.0_update.md | 0 .../developer/platyPS/CONTRIBUTING.md | 74 ++-- .../developer/platyPS/platyPS.schema.md | 0 .../presentation}/css/impress-demo.css | 0 .../platyPS/presentation}/images/FFFUUU.png | Bin .../presentation}/images/azure-maml.png | Bin .../platyPS/presentation}/images/get-help.png | Bin .../presentation}/images/markdown-github.png | Bin .../platyPS/presentation}/images/markdown.png | Bin .../images/pscmdlethelpeditor.png | Bin .../presentation}/images/psreadline-maml.png | Bin .../platyPS/presentation}/index.html | 0 .../platyPS/presentation}/js/impress.js | 0 54 files changed, 4529 insertions(+), 100 deletions(-) create mode 100644 docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Compare-CommandHelp.md create mode 100644 docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Export-MamlCommandHelp.md create mode 100644 docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Export-MarkdownCommandHelp.md create mode 100644 docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Export-MarkdownModuleFile.md create mode 100644 docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Export-YamlCommandHelp.md create mode 100644 docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Export-YamlModuleFile.md create mode 100644 docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Import-MamlHelp.md create mode 100644 docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Import-MarkdownCommandHelp.md create mode 100644 docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Import-MarkdownModuleFile.md create mode 100644 docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Import-YamlCommandHelp.md create mode 100644 docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Import-YamlModuleFile.md create mode 100644 docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Measure-PlatyPSMarkdown.md create mode 100644 docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Microsoft.PowerShell.PlatyPS.md create mode 100644 docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/New-CommandHelp.md create mode 100644 docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/New-MarkdownCommandHelp.md create mode 100644 docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/New-MarkdownModuleFile.md create mode 100644 docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Test-MarkdownCommandHelp.md create mode 100644 docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Update-CommandHelp.md create mode 100644 docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Update-MarkdownCommandHelp.md create mode 100644 docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Update-MarkdownModuleFile.md rename docs/{ => cmdlet-reference/platyPS}/Get-HelpPreview.md (100%) rename docs/{ => cmdlet-reference/platyPS}/Get-MarkdownMetadata.md (100%) rename docs/{ => cmdlet-reference/platyPS}/Merge-MarkdownHelp.md (100%) rename docs/{ => cmdlet-reference/platyPS}/New-ExternalHelp.md (100%) rename docs/{ => cmdlet-reference/platyPS}/New-ExternalHelpCab.md (100%) rename docs/{ => cmdlet-reference/platyPS}/New-MarkdownAboutHelp.md (100%) rename docs/{ => cmdlet-reference/platyPS}/New-MarkdownHelp.md (100%) rename docs/{ => cmdlet-reference/platyPS}/New-YamlHelp.md (100%) rename docs/{ => cmdlet-reference/platyPS}/Update-MarkdownHelp.md (100%) rename docs/{ => cmdlet-reference/platyPS}/Update-MarkdownHelpModule.md (100%) rename docs/{ => cmdlet-reference/platyPS}/about_platyPS.md (100%) create mode 100644 docs/developer/Microsoft.PowerShell.PlatyPS/CONTRIBUTING.md create mode 100644 docs/developer/Microsoft.PowerShell.PlatyPS/specs/PlatyPS-Design-Notes.md rename {specs => docs/developer/Microsoft.PowerShell.PlatyPS/specs}/PowerShellCmdlet.schema.json (100%) rename {specs => docs/developer/Microsoft.PowerShell.PlatyPS/specs}/PowershellCmdletV2.schema.json (100%) rename {specs => docs/developer/Microsoft.PowerShell.PlatyPS/specs}/Schema-Notes.md (100%) rename {specs => docs/developer/Microsoft.PowerShell.PlatyPS/specs}/alias-prototype.md (100%) rename {specs => docs/developer/Microsoft.PowerShell.PlatyPS/specs}/platyps_2.0_about_schema.md (100%) rename {specs => docs/developer/Microsoft.PowerShell.PlatyPS/specs}/platyps_2.0_cmdlets.md (100%) rename {specs => docs/developer/Microsoft.PowerShell.PlatyPS/specs}/platyps_2.0_update.md (100%) rename CONTRIBUTING.md => docs/developer/platyPS/CONTRIBUTING.md (56%) rename platyPS.schema.md => docs/developer/platyPS/platyPS.schema.md (100%) rename {presentation => docs/developer/platyPS/presentation}/css/impress-demo.css (100%) rename {presentation => docs/developer/platyPS/presentation}/images/FFFUUU.png (100%) rename {presentation => docs/developer/platyPS/presentation}/images/azure-maml.png (100%) rename {presentation => docs/developer/platyPS/presentation}/images/get-help.png (100%) rename {presentation => docs/developer/platyPS/presentation}/images/markdown-github.png (100%) rename {presentation => docs/developer/platyPS/presentation}/images/markdown.png (100%) rename {presentation => docs/developer/platyPS/presentation}/images/pscmdlethelpeditor.png (100%) rename {presentation => docs/developer/platyPS/presentation}/images/psreadline-maml.png (100%) rename {presentation => docs/developer/platyPS/presentation}/index.html (100%) rename {presentation => docs/developer/platyPS/presentation}/js/impress.js (100%) diff --git a/CHANGELOG.md b/CHANGELOG.md index 54d535e0..2c7d5434 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,9 +1,12 @@ -CHANGELOG -------------- +# CHANGELOG ## Not released -# 0.14.2 +## 1.0.0-preview1 + +- Total rewrite of the module in C# + +## 0.14.2 - Add HelpInfoUri for platyPS module - CI changes to exclude build on v2 branch @@ -13,21 +16,21 @@ CHANGELOG - Make sure for script module .psm1 is added to the external help file metadata for nested module - New-Yaml help generates YAML for common parameters -# 0.14.1 +## 0.14.1 - Fix appveyor build script - Update-Help for selected modules only - Pin Pester to version 4.10.1 - Add makecab directive to set size limit to `CDROM` -# 0.14.0 +## 0.14.0 * Fix passing `ExcludeDontShow` flag to modules (#459) * Make `CommonParameters` text use proper link format (#449) * Modified `GetSchemaVersion` function to assume `2.0.0` if no schema version found (#452) * Fix errors for `New-MarkdownHelp` `ps1` input (#450) -# 0.13.0 +## 0.13.0 * Fix `Update-MarkdownHelp` to not rewrite files if there are not updates (#412) (Thanks @iricigor) * Add `-ModulePagePath` parameter to `New-MarkdownHelp` for better placement of generated file (#416) (Thanks @PrzemyslawKlys) diff --git a/README.md b/README.md index f4e0fcc3..58a02fb2 100644 --- a/README.md +++ b/README.md @@ -1,50 +1,53 @@ -[![Build status](https://ci.appveyor.com/api/projects/status/u65tnar0cfkmqywl/branch/master?svg=true)](https://ci.appveyor.com/project/PowerShell/markdown-maml/branch/master) -[![Build status](https://travis-ci.org/PowerShell/platyPS.svg?branch=master)](https://travis-ci.org/PowerShell/platyPS/builds) - -[![Join the chat at https://gitter.im/PowerShell/platyPS](https://badges.gitter.im/PowerShell/platyPS.svg)](https://gitter.im/PowerShell/platyPS?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) - # PlatyPS PlatyPS provides a way to: -* Write PowerShell External Help in Markdown -* Generate markdown help ([example](docs/Update-MarkdownHelp.md)) for your existing modules -* Keep markdown help up-to-date with your code +- Write PowerShell External Help in Markdown +- Generate markdown help +- Keep markdown help up-to-date with your code +- Create updateable help files -Markdown help docs can be generated from old external help files (also known as MAML-xml help), the command objects (reflection), or both. - -PlatyPS can also generate cab files for [`Update-Help`](https://technet.microsoft.com/en-us/library/hh849720.aspx). +Markdown help docs can be generated from old external help files (also known as MAML-xml help), the +command objects (reflection), or both. ## Why? -Traditionally PowerShell external help files have been authored by hand or using complex tool chains and rendered as MAML XML for use as console help. -MAML is cumbersome to edit by hand, and common tools and editors don't support it for complex scenarios like they do with Markdown. PlatyPS is provided as a solution for allow documenting PowerShell help in any editor or tool that supports Markdown. +Traditionally PowerShell external help files have been authored by hand or using complex tool chains +and rendered as MAML XML for use as console help. MAML is cumbersome to edit by hand, and common +tools and editors don't support it for complex scenarios like they do with Markdown. PlatyPS is +provided as a solution for allow documenting PowerShell help in any editor or tool that supports +Markdown. -An additional challenge PlatyPS tackles, is to handle PowerShell documentation for complex scenarios (e.g. very large, closed source, and/or C#/binary modules) where it may be desirable to have documentation abstracted away from the codebase. PlatyPS does not need source access to generate documentation. +An additional challenge PlatyPS tackles, is to handle PowerShell documentation for complex scenarios +(e.g. very large, closed source, and/or C#/binary modules) where it may be desirable to have +documentation abstracted away from the codebase. PlatyPS doesn't need source access to generate +documentation. -Markdown is designed to be human-readable, without rendering. This makes writing and editing easy and efficient. -Many editors support it ([Visual Studio Code](https://code.visualstudio.com/), [Sublime Text](http://www.sublimetext.com/), etc), and many tools and collaboration platforms (GitHub, Visual Studio Online) render the Markdown nicely. +Markdown is designed to be human-readable, without rendering. This makes writing and editing easy +and efficient. Many editors support it, including [Visual Studio Code][04], and many tools and +collaboration platforms (GitHub, Visual Studio Online) render the Markdown nicely. ## Common setups There are 2 common setups that are used: 1. Use markdown as the source of truth and remove other types of help. -2. Keep comment based help as the source of truth and periodically generate markdown for web-site publishing. +1. Keep comment based help as the source of truth and periodically generate markdown for web-site + publishing. -They both have advantages and use-cases, you should decide what's right for you. -There is slight preference toward number 1 (markdown as the source). +They both have advantages and use-cases, you should decide what's right for you. There is slight +preference toward number 1 (markdown as the source). ## Quick start -* Install platyPS module from the [PowerShell Gallery](https://www.powershellgallery.com/packages/platyPS): +- Install platyPS module from the [PowerShell Gallery][07]: ```powershell Install-Module -Name platyPS -Scope CurrentUser Import-Module platyPS ``` -* Create initial Markdown help for `MyAwesomeModule` module: +- Create initial Markdown help for `MyAwesomeModule` module: ```powershell # you should have module imported in the session @@ -52,72 +55,77 @@ Import-Module MyAwesomeModule New-MarkdownHelp -Module MyAwesomeModule -OutputFolder .\docs ``` -* Edit markdown files in `.\docs` folder and populate `{{ ... }}` placeholders with missed help content. +- Edit markdown files in `.\docs` folder and populate `{{ ... }}` placeholders with missed help content. +- Create external help from markdown help -* Create external help from markdown help + ```powershell + New-ExternalHelp .\docs -OutputPath en-US\ + ``` -```powershell -New-ExternalHelp .\docs -OutputPath en-US\ -``` - -* **Congratulations**, your help is now in markdown! + **Congratulations**, your help is now in markdown! -* Now, if your module code changes, you can easily update your markdown help with +- Now, if your module code changes, you can easily update your markdown help with -```powershell -# re-import your module with latest changes -Import-Module MyAwesomeModule -Force -Update-MarkdownHelp .\docs -``` + ```powershell + # re-import your module with latest changes + Import-Module MyAwesomeModule -Force + Update-MarkdownHelp .\docs + ``` ### PlatyPS markdown schema -Unfortunately, you cannot just write any Markdown, as platyPS expects Markdown to be authored in a **particular way**. -We have defined a [**schema**](platyPS.schema.md) to determine how parameters are described, where scripts examples are shown, and so on. +Unfortunately, you cannot just write any Markdown, as platyPS expects Markdown to be authored in a +**particular way**. We have defined a [**schema**][03] to determine how parameters are described, +where scripts examples are shown, and so on. -The schema closely resembles the existing output format of the `Get-Help` cmdlet in PowerShell. +The schema closely resembles the existing output format of the `Get-Help` cmdlet in PowerShell. -If you break the schema in your markdown, you will get error messages from `New-ExternalHelp` and `Update-MarkdownHelp`. -You would not be able to generate extrenal help or update your markdown. +If you break the schema in your markdown, you will get error messages from `New-ExternalHelp` and +`Update-MarkdownHelp`. You would not be able to generate extrenal help or update your markdown. It may be fine for some scenarios, i.e. you want to have online-only version of markdown. -## [Usage](docs) +## [Usage][06] Supported scenarios: -* Create Markdown - * Using existing external help files (MAML schema, XML). - * Using reflection - * Using reflection and existing internal external help files. - * For a single cmdlet - * For an entire module - -* Update existing Markdown through reflection. - -* Create a module page .md with summary. It will also allow you to create updatable help cab. - -* Retrieve markdown metadata from markdown file. - -* Create external help xml files (MAML) from platyPS Markdown. - -* Create external help file cab - -* Preview help from generated maml file. +- Create Markdown + - Using existing external help files (MAML schema, XML). + - Using reflection + - Using reflection and existing internal external help files. + - For a single cmdlet + - For an entire module +- Update existing Markdown through reflection. +- Create a module page `.md` with summary. It will also allow you to create updatable + help cab. +- Retrieve markdown metadata from markdown file. +- Create external help xml files (MAML) from platyPS Markdown. +- Create external help file cab +- Preview help from generated maml file. ## Remoting -PlatyPS supports working with [`Import-PSSession`](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.utility/import-pssession?view=powershell-6) aka implicit remoting. -Just pass `-Session $Session` parameter to the platyPS cmdlets and it will do the rest. +PlatyPS supports working with [Import-PSSession][05] aka implicit remoting. Just pass +`-Session $Session` parameter to the platyPS cmdlets and it will do the rest. ## Build -For information about building from sources and contributing see [contributing guidelines](CONTRIBUTING.md). +For information about building from sources and contributing see [contributing guidelines][02]. ## Code of Conduct -Please see our [Code of Conduct](CODE_OF_CONDUCT.md) before participating in this project. +Please see our [Code of Conduct][01] before participating in this project. ## Security Policy -For any security issues, please see our [Security Policy](SECURITY.md). +For any security issues, please see our [Security Policy][08]. + + +[01]: CODE_OF_CONDUCT.md +[02]: docs/developer/platyPS/CONTRIBUTING.md +[03]: docs/deveopler/platyPS.schema.md +[04]: https://code.visualstudio.com/ +[05]: https://docs.microsoft.com/powershell/module/microsoft.powershell.utility/import-pssession +[06]: https://learn.microsoft.com/powershell/module/platyps/ +[07]: https://www.powershellgallery.com/packages/platyPS +[08]: SECURITY.md diff --git a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Compare-CommandHelp.md b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Compare-CommandHelp.md new file mode 100644 index 00000000..4eb024dc --- /dev/null +++ b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Compare-CommandHelp.md @@ -0,0 +1,134 @@ +--- +document type: cmdlet +external help file: Microsoft.PowerShell.PlatyPS.dll-Help.xml +HelpUri: '' +Locale: en-US +Module Name: Microsoft.PowerShell.PlatyPS +ms.custom: OPS10 +ms.date: 09/17/2024 +PlatyPS schema version: 2024-05-01 +title: Compare-CommandHelp +--- + +# Compare-CommandHelp + +## SYNOPSIS + +Compares two **CommandHelp** objects and produces a detailed report showing the differences. + +## SYNTAX + +### __AllParameterSets + +``` +Compare-CommandHelp [-ReferenceCommandHelp] [-DifferenceCommandHelp] + [-PropertyNamesToExclude ] [] +``` + +## ALIASES + +## DESCRIPTION + +`Compare-CommandHelp` is a troubleshooting tool that compares two CommandHelp objects and produces a +detailed report showing the differences. For example, you can use this to compare objects imported +from different sources, such as two different versions of Markdown files. + +## EXAMPLES + +### Example 1 + +```powershell +$refcmd = Import-MarkdownCommandHelp -Path .\v1\Microsoft.PowerShell.PlatyPS\Compare-CommandHelp.md +$diffcmd = Import-MarkdownCommandHelp -Path .\v2\Microsoft.PowerShell.PlatyPS\Compare-CommandHelp.md +Compare-CommandHelp -ReferenceCommandHelp $refcmd -DifferenceCommandHelp $diffcmd > .\diff.log +``` + +## PARAMETERS + +### -DifferenceCommandHelp + +The CommandHelp object to compare against the reference object. + +```yaml +Type: Microsoft.PowerShell.PlatyPS.Model.CommandHelp +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: [] +ParameterSets: +- Name: (All) + Position: 1 + IsRequired: true + ValueFromPipeline: false + ValueFromPipelineByPropertyName: true + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -PropertyNamesToExclude + +A list of one or more property names to exclude from the comparison. + +```yaml +Type: System.String[] +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: [] +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -ReferenceCommandHelp + +The base CommandHelp object to be compared to the difference object. + +```yaml +Type: Microsoft.PowerShell.PlatyPS.Model.CommandHelp +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: [] +ParameterSets: +- Name: (All) + Position: 0 + IsRequired: true + ValueFromPipeline: false + ValueFromPipelineByPropertyName: true + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, +-ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### Microsoft.PowerShell.PlatyPS.Model.CommandHelp + +## OUTPUTS + +### System.String + +## NOTES + +## RELATED LINKS + +- [Import-MarkdownHelp](Import-MarkdownHelp.md) +- [Import-YamlCommandHelp](Import-YamlCommandHelp.md) diff --git a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Export-MamlCommandHelp.md b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Export-MamlCommandHelp.md new file mode 100644 index 00000000..e5d4c4ce --- /dev/null +++ b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Export-MamlCommandHelp.md @@ -0,0 +1,210 @@ +--- +document type: cmdlet +external help file: Microsoft.PowerShell.PlatyPS.dll-Help.xml +HelpUri: '' +Locale: en-US +Module Name: Microsoft.PowerShell.PlatyPS +ms.custom: OPS10 +ms.date: 09/17/2024 +PlatyPS schema version: 2024-05-01 +title: Export-MamlCommandHelp +--- + +# Export-MamlCommandHelp + +## SYNOPSIS + +Exports **CommandHelp** objects to a MAML file. + +## SYNTAX + +### __AllParameterSets + +``` +Export-MamlCommandHelp [-CommandHelp] [-OutputFolder] + [-Encoding ] [-Force] [-WhatIf] [-Confirm] [] +``` + +## ALIASES + +## DESCRIPTION + +This command converts **CommandHelp** objects to a MAML file. The MAML file contains help content in +the format used by the `Get-Help` command. + +## EXAMPLES + +### Example 1 - Create the MAML help file for a module + +```powershell +$mdfiles = Measure-PlatyPSMarkdown -Path .\v2\Microsoft.PowerShell.PlatyPS\*.md +$mdfiles | Where-Object Filetype -match 'CommandHelp' | + Import-MarkdownCommandHelp -Path {$_.FilePath} | + Export-MamlCommandHelp -OutputFolder .\maml +``` + +```Output + Directory: D:\Git\PS-Src\platyPS\v2docs\maml + +Mode LastWriteTime Length Name +---- ------------- ------ ---- +-a--- 8/26/2024 3:18 PM 160928 Microsoft.PowerShell.PlatyPS-Help.xml +``` + +## PARAMETERS + +### -CommandHelp + +One or more **CommandHelp** objects to export. + +```yaml +Type: Microsoft.PowerShell.PlatyPS.Model.CommandHelp[] +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: [] +ParameterSets: +- Name: (All) + Position: 0 + IsRequired: true + ValueFromPipeline: true + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -Confirm + +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: System.Management.Automation.SwitchParameter +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: +- cf +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -Encoding + +The encoding to use when writing the markdown file. If no value is specified, encoding defaults to +the value of the `$OutputEncoding` preference variable. + +```yaml +Type: System.Text.Encoding +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: [] +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -Force + +Use the **Force** parameter to overwrite the output file if it already exists. + +```yaml +Type: System.Management.Automation.SwitchParameter +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: [] +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -OutputFolder + +The folder where the markdown file is saved. If the folder doesn't exist, it's created. + +```yaml +Type: System.String +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: [] +ParameterSets: +- Name: (All) + Position: 1 + IsRequired: true + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -WhatIf + +Shows what would happen if the cmdlet runs. The cmdlet isn't run. + +```yaml +Type: System.Management.Automation.SwitchParameter +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: +- wi +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, +-ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### Microsoft.PowerShell.PlatyPS.Model.CommandHelp + +## OUTPUTS + +### System.IO.FileInfo + +## NOTES + +## RELATED LINKS + +- [Import-MarkdownCommandHelp](Import-MarkdownCommandHelp.md) diff --git a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Export-MarkdownCommandHelp.md b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Export-MarkdownCommandHelp.md new file mode 100644 index 00000000..be65fcec --- /dev/null +++ b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Export-MarkdownCommandHelp.md @@ -0,0 +1,279 @@ +--- +document type: cmdlet +external help file: Microsoft.PowerShell.PlatyPS.dll-Help.xml +HelpUri: '' +Locale: en-US +Module Name: Microsoft.PowerShell.PlatyPS +ms.custom: OPS10 +ms.date: 09/17/2024 +PlatyPS schema version: 2024-05-01 +title: Export-MarkdownCommandHelp +--- + +# Export-MarkdownCommandHelp + +## SYNOPSIS + +Exports a **CommandHelp** object to a markdown file. + +## SYNTAX + +### __AllParameterSets + +``` +Export-MarkdownCommandHelp [-CommandHelp] [-Encoding ] [-Force] + [-OutputFolder ] [-Metadata ] [-WhatIf] [-Confirm] [] +``` + +## ALIASES + +## DESCRIPTION + +This command exports a **CommandHelp** object to a markdown file. You can add metadata frontmatter +to the markdown file by using the **Metadata** parameter. You can get a **CommandHelp** object by +using the `Export-MarkdownCommandHelp` cmdlet or one of the `Import-*` cmdlets. + +## EXAMPLES + +### Example 1 - Convert old Markdown help content to the new format + +This example imports Markdown help in the old format from the `.\v1` folder and exports it to the +`.\v2` folder in the new format. + +```powershell +$chobj = Import-MarkdownCommandHelp -Path .\v1\Export-YamlModuleFile.md +Export-MarkdownCommandHelp -CommandHelp $chobj -OutputFolder .\v2 +``` + +```Output + Directory: D:\Git\PS-Src\platyPS\v2docs\v2 + +Mode LastWriteTime Length Name +---- ------------- ------ ---- +-a--- 5/20/2024 3:33 PM 2892 Export-YamlModuleFile.md +``` + +### Example 2 - Convert a folder of old Markdown help content to the new format + +This example imports Markdown help in the old format from the `.\v1` folder and exports it to the +`.\v1\new` folder in the new format. If necessary, `Export-MarkdownCommandHelp` creates the +destination folders. The new markdown files are written to folder named for the module they belong +to. + +```powershell +$mdfiles = Measure-PlatyPSMarkdown -Path .\v1\Microsoft.PowerShell.PlatyPS\*.md +$mdfiles | Where-Object Filetype -match 'CommandHelp' | + Import-MarkdownCommandHelp -Path {$_.FilePath} | + Export-MarkdownCommandHelp -OutputFolder .\v1\new +``` + +```Output + Directory: D:\Git\PS-Src\platyPS\v2docs\v1\new\Microsoft.PowerShell.PlatyPS + +Mode LastWriteTime Length Name +---- ------------- ------ ---- +-a--- 8/26/2024 3:30 PM 3194 Compare-CommandHelp.md +-a--- 8/26/2024 3:30 PM 4282 Export-MamlCommandHelp.md +-a--- 8/26/2024 3:30 PM 6401 Export-MarkdownCommandHelp.md +-a--- 8/26/2024 3:30 PM 4874 Export-MarkdownModuleFile.md +-a--- 8/26/2024 3:30 PM 6429 Export-YamlCommandHelp.md +-a--- 8/26/2024 3:30 PM 5601 Export-YamlModuleFile.md +-a--- 8/26/2024 3:30 PM 2724 Import-MamlHelp.md +-a--- 8/26/2024 3:30 PM 3733 Import-MarkdownCommandHelp.md +-a--- 8/26/2024 3:30 PM 3870 Import-MarkdownModuleFile.md +-a--- 8/26/2024 3:30 PM 3907 Import-YamlCommandHelp.md +-a--- 8/26/2024 3:30 PM 3477 Import-YamlModuleFile.md +-a--- 8/26/2024 3:30 PM 2088 Measure-PlatyPSMarkdown.md +-a--- 8/26/2024 3:30 PM 4748 New-CommandHelp.md +-a--- 8/26/2024 3:30 PM 8647 New-MarkdownCommandHelp.md +-a--- 8/26/2024 3:30 PM 5086 New-MarkdownModuleFile.md +-a--- 8/26/2024 3:30 PM 3080 Test-MarkdownCommandHelp.md +-a--- 8/26/2024 3:30 PM 3041 Update-CommandHelp.md +-a--- 8/26/2024 3:30 PM 3981 Update-MarkdownCommandHelp.md +-a--- 8/26/2024 3:30 PM 5548 Update-MarkdownModuleFile.md +``` + +## PARAMETERS + +### -CommandHelp + +The **CommandHelp** object to export. You can pass the **CommandHelp** object on the pipeline or by +using the **Command** parameter. + +```yaml +Type: Microsoft.PowerShell.PlatyPS.Model.CommandHelp[] +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: [] +ParameterSets: +- Name: (All) + Position: 0 + IsRequired: true + ValueFromPipeline: true + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -Confirm + +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: System.Management.Automation.SwitchParameter +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: +- cf +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -Encoding + +The encoding to use when writing the markdown file. If no value is specified, encoding defaults to +the value of the `$OutputEncoding` preference variable. + +```yaml +Type: System.Text.Encoding +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: [] +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -Force + +Use the **Force** parameter to overwrite the output file if it already exists. + +```yaml +Type: System.Management.Automation.SwitchParameter +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: [] +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -Metadata + +The metadata to add to the frontmatter of the markdown file. The metadata is a hashtable where the +you specify the key and value pairs to add to the frontmatter. New key names are added to the +existing frontmatter. The values of existing keys are overwritten. + +```yaml +Type: System.Collections.Hashtable +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: [] +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -OutputFolder + +The folder where the markdown file is saved. If the folder doesn't exist, it's created. + +```yaml +Type: System.String +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: [] +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -WhatIf + +Shows what would happen if the cmdlet runs. The cmdlet is not run. + +```yaml +Type: System.Management.Automation.SwitchParameter +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: +- wi +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, +-ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### Microsoft.PowerShell.PlatyPS.Model.CommandHelp + +## OUTPUTS + +### System.IO.FileInfo + +## NOTES + +## RELATED LINKS + +- [Export-YamlCommandHelp](Export-YamlCommandHelp.md) +- [Import-MarkdownCommandHelp](Import-MarkdownCommandHelp.md) +- [Import-YamlCommandHelp](Import-YamlCommandHelp.md) diff --git a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Export-MarkdownModuleFile.md b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Export-MarkdownModuleFile.md new file mode 100644 index 00000000..6f854af4 --- /dev/null +++ b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Export-MarkdownModuleFile.md @@ -0,0 +1,239 @@ +--- +document type: cmdlet +external help file: Microsoft.PowerShell.PlatyPS.dll-Help.xml +HelpUri: '' +Locale: en-US +Module Name: Microsoft.PowerShell.PlatyPS +ms.custom: OPS10 +ms.date: 09/17/2024 +PlatyPS schema version: 2024-05-01 +title: Export-MarkdownModuleFile +--- + +# Export-MarkdownModuleFile + +## SYNOPSIS + +Exports a **ModuleFileInfo** object to a markdown file. + +## SYNTAX + +### __AllParameterSets + +``` +Export-MarkdownModuleFile [-ModuleFileInfo] [-Encoding ] [-Force] + [-Metadata ] [-OutputFolder ] [-WhatIf] [-Confirm] [] +``` + +## ALIASES + +## DESCRIPTION + +This command exports a **ModuleFileInfo** object to a markdown file. You can add metadata +frontmatter to the markdown file by using the **Metadata** parameter. You can get a +**ModuleFileInfo** object by using the `Import-MarkdownModuleFile` cmdlet. You can import a module +file that's written in the old format and export it to the new format. + +## EXAMPLES + +### Example 1 - Convert an old module file to the new format + +In this example, a **ModuleFileInfo** object by importing a module Markdown file from the `.\v1` +folder. That object is then exported to a Markdown file in the new format using the +`Export-MarkdownModuleFile`. + +```powershell +Import-MarkdownModuleFile -Path .\v1\Microsoft.PowerShell.PlatyPS\Microsoft.PowerShell.PlatyPS.md | + Export-MarkdownModuleFile -OutputFolder .\v1\new\Microsoft.PowerShell.PlatyPS -Force +``` + +```Output + Directory: D:\Git\PS-Src\platyPS\v2docs\v1\new\Microsoft.PowerShell.PlatyPS + +Mode LastWriteTime Length Name +---- ------------- ------ ---- +-a--- 8/26/2024 3:38 PM 2716 Microsoft.PowerShell.PlatyPS.md +``` + +## PARAMETERS + +### -Confirm + +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: System.Management.Automation.SwitchParameter +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: +- cf +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -Encoding + +The encoding to use when writing the markdown file. If no value is specified, encoding defaults to +the value of the `$OutputEncoding` preference variable. + +```yaml +Type: System.Text.Encoding +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: [] +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -Force + +Use the **Force** parameter to overwrite the output file if it already exists. + +```yaml +Type: System.Management.Automation.SwitchParameter +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: [] +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -Metadata + +The metadata to add to the frontmatter of the markdown file. The metadata is a hashtable where the +you specify the key and value pairs to add to the frontmatter. New key names are added to the +existing frontmatter. The values of existing keys are overwritten. + +```yaml +Type: System.Collections.Hashtable +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: [] +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -ModuleFileInfo + +The **ModuleFileInfo** object to export to a markdown file. This object is created by the +`Import-MarkdownModuleFile` cmdlet. + +```yaml +Type: Microsoft.PowerShell.PlatyPS.ModuleFileInfo[] +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: [] +ParameterSets: +- Name: (All) + Position: 0 + IsRequired: true + ValueFromPipeline: true + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -OutputFolder + +The folder where the markdown file is saved. If the folder doesn't exist, it's created. + +```yaml +Type: System.String +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: [] +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -WhatIf + +Shows what would happen if the cmdlet runs. The cmdlet isn't run. + +```yaml +Type: System.Management.Automation.SwitchParameter +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: +- wi +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, +-ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### Microsoft.PowerShell.PlatyPS.ModuleFileInfo + +## OUTPUTS + +### System.IO.FileInfo + +## NOTES + +## RELATED LINKS + +- [Import-MarkdownModuleFile](Import-MarkdownModuleFile.md) diff --git a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Export-YamlCommandHelp.md b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Export-YamlCommandHelp.md new file mode 100644 index 00000000..cc6a8b16 --- /dev/null +++ b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Export-YamlCommandHelp.md @@ -0,0 +1,260 @@ +--- +document type: cmdlet +external help file: Microsoft.PowerShell.PlatyPS.dll-Help.xml +HelpUri: '' +Locale: en-US +Module Name: Microsoft.PowerShell.PlatyPS +ms.custom: OPS10 +ms.date: 09/17/2024 +PlatyPS schema version: 2024-05-01 +title: Export-YamlCommandHelp +--- + +# Export-YamlCommandHelp + +## SYNOPSIS + +Exports **CommandHelp** objects to YAML files. + +## SYNTAX + +### __AllParameterSets + +``` +Export-YamlCommandHelp [-CommandHelp] [-Encoding ] [-Force] + [-OutputFolder ] [-Metadata ] [-WhatIf] [-Confirm] [] +``` + +## ALIASES + +## DESCRIPTION + +This command exports a **CommandHelp** object to a Yaml file. You can add metadata frontmatter +to the Yaml file by using the **Metadata** parameter. You can get a **CommandHelp** object by +using the `Export-YamlCommandHelp` cmdlet or one of the `Import-*` cmdlets. + +## EXAMPLES + +### Example 1 - Convert Markdown command help content to Yaml format + +This example imports Markdown help in the old format from the `.\v1` folder and exports it to the +`.\v2` folder in the new format. + +```powershell +$mdfiles = Measure-PlatyPSMarkdown -Path .\v2\Microsoft.PowerShell.PlatyPS\*.md +$mdfiles | Where-Object Filetype -match 'CommandHelp' | + Import-MarkdownCommandHelp -Path {$_.FilePath} | + Export-YamlCommandHelp -OutputFolder .\v2\yaml +``` + +```Output + Directory: D:\Git\PS-Src\platyPS\v2docs\v2\yaml + +Mode LastWriteTime Length Name +---- ------------- ------ ---- +-a--- 8/26/2024 3:56 PM 3535 Compare-CommandHelp.yml +-a--- 8/26/2024 3:56 PM 4776 Export-MamlCommandHelp.yml +-a--- 8/26/2024 3:56 PM 8150 Export-MarkdownCommandHelp.yml +-a--- 8/26/2024 3:56 PM 4998 Export-MarkdownModuleFile.yml +-a--- 8/26/2024 3:56 PM 6357 Export-YamlCommandHelp.yml +-a--- 8/26/2024 3:56 PM 5396 Export-YamlModuleFile.yml +-a--- 8/26/2024 3:56 PM 3019 Import-MamlHelp.yml +-a--- 8/26/2024 3:56 PM 4235 Import-MarkdownCommandHelp.yml +-a--- 8/26/2024 3:56 PM 4318 Import-MarkdownModuleFile.yml +-a--- 8/26/2024 3:56 PM 4391 Import-YamlCommandHelp.yml +-a--- 8/26/2024 3:56 PM 3862 Import-YamlModuleFile.yml +-a--- 8/26/2024 3:56 PM 2325 Measure-PlatyPSMarkdown.yml +-a--- 8/26/2024 3:56 PM 5190 New-CommandHelp.yml +-a--- 8/26/2024 3:56 PM 8335 New-MarkdownCommandHelp.yml +-a--- 8/26/2024 3:56 PM 4697 New-MarkdownModuleFile.yml +-a--- 8/26/2024 3:56 PM 3468 Test-MarkdownCommandHelp.yml +-a--- 8/26/2024 3:56 PM 3172 Update-CommandHelp.yml +-a--- 8/26/2024 3:56 PM 3908 Update-MarkdownCommandHelp.yml +-a--- 8/26/2024 3:56 PM 5217 Update-MarkdownModuleFile.yml +``` + +## PARAMETERS + +### -CommandHelp + +The **CommandHelp** object to export. You can pass the **CommandHelp** object on the pipeline or by +using the **Command** parameter. + +```yaml +Type: Microsoft.PowerShell.PlatyPS.Model.CommandHelp[] +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: [] +ParameterSets: +- Name: (All) + Position: 0 + IsRequired: true + ValueFromPipeline: true + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -Confirm + +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: System.Management.Automation.SwitchParameter +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: +- cf +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -Encoding + +The encoding to use when writing the markdown file. If no value is specified, encoding defaults to +the value of the `$OutputEncoding` preference variable. + +```yaml +Type: System.Text.Encoding +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: [] +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -Force + +Use the **Force** parameter to overwrite the output file if it already exists. + +```yaml +Type: System.Management.Automation.SwitchParameter +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: [] +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -Metadata + +The metadata to add to the frontmatter of the markdown file. The metadata is a hashtable where the +you specify the key and value pairs to add to the frontmatter. New key names are added to the +existing frontmatter. The values of existing keys are overwritten. + +```yaml +Type: System.Collections.Hashtable +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: [] +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -OutputFolder + +The folder where the markdown file is saved. If the folder doesn't exist, it's created. + +```yaml +Type: System.String +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: [] +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -WhatIf + +Shows what would happen if the cmdlet runs. The cmdlet isn't run. + +```yaml +Type: System.Management.Automation.SwitchParameter +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: +- wi +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, +-ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### Microsoft.PowerShell.PlatyPS.Model.CommandHelp + +## OUTPUTS + +### System.IO.FileInfo + +## NOTES + +## RELATED LINKS + +- [Export-YamlCommandHelp](Export-YamlCommandHelp.md) +- [Export-MarkdownCommandHelp](Export-MarkdownCommandHelp.md) +- [Import-MarkdownCommandHelp](Import-MarkdownCommandHelp.md) +- [Import-YamlCommandHelp](Import-YamlCommandHelp.md) diff --git a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Export-YamlModuleFile.md b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Export-YamlModuleFile.md new file mode 100644 index 00000000..ac307a5f --- /dev/null +++ b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Export-YamlModuleFile.md @@ -0,0 +1,237 @@ +--- +document type: cmdlet +external help file: Microsoft.PowerShell.PlatyPS.dll-Help.xml +HelpUri: '' +Locale: en-US +Module Name: Microsoft.PowerShell.PlatyPS +ms.custom: OPS10 +ms.date: 09/17/2024 +PlatyPS schema version: 2024-05-01 +title: Export-YamlModuleFile +--- + +# Export-YamlModuleFile + +## SYNOPSIS + +Exports a **ModuleFileInfo** object to a Yaml file. + +## SYNTAX + +### __AllParameterSets + +``` +Export-YamlModuleFile [-ModuleFileInfo] [-Encoding ] [-Force] + [-OutputFolder ] [-Metadata ] [-WhatIf] [-Confirm] [] +``` + +## ALIASES + +## DESCRIPTION + +This command exports a **ModuleFileInfo** object to a markdown file. You can get a +**ModuleFileInfo** object by using the `Import-MarkdownModuleFile` cmdlet. You can import a module +file that's written in the old format and export it to the new format. + +## EXAMPLES + +### Example 1 - Export a ModuleFileInfo object to a markdown file + +In this example, a **ModuleFileInfo** object by importing a module Markdown file. That object is +then exported to a Yaml file using the `Export-YamlModuleFile`. + +```powershell +Import-MarkdownModuleFile -Path .\v2\Microsoft.PowerShell.PlatyPS\Microsoft.PowerShell.PlatyPS.md | + Export-YamlModuleFile -OutputFolder .\v2\yaml +``` + +```Output + Directory: D:\Git\PS-Src\platyPS\v2docs\v2\yaml + +Mode LastWriteTime Length Name +---- ------------- ------ ---- +-a--- 8/26/2024 4:00 PM 2594 Microsoft.PowerShell.PlatyPS.yml +``` + +## PARAMETERS + +### -Confirm + +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: System.Management.Automation.SwitchParameter +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: +- cf +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -Encoding + +The encoding to use when writing the markdown file. If no value is specified, encoding defaults to +the value of the `$OutputEncoding` preference variable. + +```yaml +Type: System.Text.Encoding +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: [] +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -Force + +Use the **Force** parameter to overwrite the output file if it already exists. + +```yaml +Type: System.Management.Automation.SwitchParameter +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: [] +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -Metadata + +The metadata to add to the markdown file. The metadata is a hashtable that contains key-value pairs. + +```yaml +Type: System.Collections.Hashtable +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: [] +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -ModuleFileInfo + +The **ModuleFileInfo** object to export. You can pass the **ModuleFileInfo** object on the pipeline +or by using the **ModuleFileInfo** parameter. + +```yaml +Type: Microsoft.PowerShell.PlatyPS.ModuleFileInfo[] +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: [] +ParameterSets: +- Name: (All) + Position: 0 + IsRequired: true + ValueFromPipeline: true + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -OutputFolder + +The **ModuleFileInfo** object to export to a markdown file. This object is created by the +`Import-MarkdownModuleFile` cmdlet. + +```yaml +Type: System.String +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: [] +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -WhatIf + +Shows what would happen if the cmdlet runs. The cmdlet isn't run. + +```yaml +Type: System.Management.Automation.SwitchParameter +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: +- wi +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, +-ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### Microsoft.PowerShell.PlatyPS.ModuleFileInfo + +## OUTPUTS + +### System.IO.FileInfo + +## NOTES + +## RELATED LINKS + +- [Export-MarkdownModuleFile](Export-MarkdownModuleFile.md) +- [Import-MarkdownModuleFile](Import-MarkdownModuleFile.md) diff --git a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Import-MamlHelp.md b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Import-MamlHelp.md new file mode 100644 index 00000000..bd4c3373 --- /dev/null +++ b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Import-MamlHelp.md @@ -0,0 +1,124 @@ +--- +document type: cmdlet +external help file: Microsoft.PowerShell.PlatyPS.dll-Help.xml +HelpUri: '' +Locale: en-US +Module Name: Microsoft.PowerShell.PlatyPS +ms.custom: OPS10 +ms.date: 09/17/2024 +PlatyPS schema version: 2024-05-01 +title: Import-MamlHelp +--- + +# Import-MamlHelp + +## SYNOPSIS + +Imports MAML help from a file and creates **CommandHelp** objects for each command in the file. + +## SYNTAX + +### Path (Default) + +``` +Import-MamlHelp [-Path] [] +``` + +### LiteralPath + +``` +Import-MamlHelp -LiteralPath [] +``` + +## ALIASES + +## DESCRIPTION + +This command can be used to create **CommandHelp** objects from MAML help files. These objects can +be used to generate Markdown help files. You can also use this command to test the validity of the +MAML help files. + +## EXAMPLES + +### Example 1 + +```powershell +Import-MamlHelp -Path .\maml\Microsoft.PowerShell.PlatyPS.dll-Help.xml +``` + +## PARAMETERS + +### -LiteralPath + +The path to the MAML help file. Specifies a path to one or more locations. The value of LiteralPath +is used exactly as it's typed. No characters are interpreted as wildcards. If the path includes +escape characters, enclose it in single quotation marks. Single quotation marks tell PowerShell not +to interpret any characters as escape sequences. + +For more information, see +[about_Quoting_Rules](/powershell/module/microsoft.powershell.core/about/about_quoting_rules). + +```yaml +Type: System.String[] +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: [] +ParameterSets: +- Name: LiteralPath + Position: Named + IsRequired: true + ValueFromPipeline: false + ValueFromPipelineByPropertyName: true + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -Path + +The path to the MAML help file. Specifies a path to one or more locations. + +```yaml +Type: System.String[] +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: [] +ParameterSets: +- Name: Path + Position: 0 + IsRequired: true + ValueFromPipeline: true + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, +-ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### System.String + +## OUTPUTS + +### Microsoft.PowerShell.PlatyPS.Model.CommandHelp + +## NOTES + +The MAML file format doesn't support all the information that can be stored in a **CommandHelp** +object. If you convert the imported information to markdown format, the resulting markdown file +is not a complete representation of the original command. + +## RELATED LINKS + +- [Export-MamlHelp](Export-MamlCommandHelp.md) diff --git a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Import-MarkdownCommandHelp.md b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Import-MarkdownCommandHelp.md new file mode 100644 index 00000000..aaf2a5c5 --- /dev/null +++ b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Import-MarkdownCommandHelp.md @@ -0,0 +1,156 @@ +--- +document type: cmdlet +external help file: Microsoft.PowerShell.PlatyPS.dll-Help.xml +HelpUri: '' +Locale: en-US +Module Name: Microsoft.PowerShell.PlatyPS +ms.custom: OPS10 +ms.date: 09/17/2024 +PlatyPS schema version: 2024-05-01 +title: Import-MarkdownCommandHelp +--- + +# Import-MarkdownCommandHelp + +## SYNOPSIS + +Imports Markdown help content into **CommandHelp** objects. + +## SYNTAX + +### Path (Default) + +``` +Import-MarkdownCommandHelp [-Path] [] +``` + +### LiteralPath + +``` +Import-MarkdownCommandHelp -LiteralPath [] +``` + +## ALIASES + +## DESCRIPTION + +The command imports Markdown files containing command help and creates **CommandHelp** objects. The +**CommandHelp** object is a structured representation of the help content that can be used to export +to different formats. + +## EXAMPLES + +### Example 1 - Import all cmdlet Markdown files in a folder + +The following example import cmdlet Markdown files in a folder and converts them to **CommandHelp** +objects. These objects can be used to export to different formats. + +```powershell +$mdfiles = Measure-PlatyPSMarkdown -Path .\v2\Microsoft.PowerShell.PlatyPS\*.md +$mdfiles | Where-Object Filetype -match 'CommandHelp' | + Import-MarkdownCommandHelp -Path {$_.FilePath} | + Select-Object Title +``` + +```Output +Title +----- +Compare-CommandHelp +Export-MamlCommandHelp +Export-MarkdownCommandHelp +Export-MarkdownModuleFile +Export-YamlCommandHelp +Export-YamlModuleFile +Import-MamlHelp +Import-MarkdownCommandHelp +Import-MarkdownModuleFile +Import-YamlCommandHelp +Import-YamlModuleFile +Measure-PlatyPSMarkdown +New-CommandHelp +New-MarkdownCommandHelp +New-MarkdownModuleFile +Test-MarkdownCommandHelp +Update-CommandHelp +Update-MarkdownCommandHelp +Update-MarkdownModuleFile +``` + +## PARAMETERS + +### -LiteralPath + +Specifies a path to one or more locations containing markdown files. The value of **LiteralPath** is +used exactly as it's typed. No characters are interpreted as wildcards. If the path includes escape +characters, enclose it in single quotation marks. Single quotation marks tell PowerShell not to +interpret any characters as escape sequences. + +For more information, see +[about_Quoting_Rules](/powershell/module/microsoft.powershell.core/about/about_CommonParameters). + +```yaml +Type: System.String[] +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: [] +ParameterSets: +- Name: LiteralPath + Position: Named + IsRequired: true + ValueFromPipeline: true + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -Path + +Specifies the path to an item. This cmdlet gets the item at the specified location. Wildcard +characters are permitted. This parameter is required, but the parameter name Path is optional. + +Use a dot (`.`) to specify the current location. Use the wildcard character (`*`) to specify all +items in the current location. + +```yaml +Type: System.String[] +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: [] +ParameterSets: +- Name: Path + Position: 0 + IsRequired: true + ValueFromPipeline: true + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, +-ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### System.String + +## OUTPUTS + +### Microsoft.PowerShell.PlatyPS.Model.CommandHelp + +## NOTES + +## RELATED LINKS + +- [Export-MarkdownCommandHelp](Export-MarkdownCommandHelp.md) +- [Export-YamlCommandHelp](Export-YamlCommandHelp.md) +- [Import-YamlCommandHelp](Import-YamlCommandHelp.md) diff --git a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Import-MarkdownModuleFile.md b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Import-MarkdownModuleFile.md new file mode 100644 index 00000000..9849f19d --- /dev/null +++ b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Import-MarkdownModuleFile.md @@ -0,0 +1,138 @@ +--- +document type: cmdlet +external help file: Microsoft.PowerShell.PlatyPS.dll-Help.xml +HelpUri: '' +Locale: en-US +Module Name: Microsoft.PowerShell.PlatyPS +ms.custom: OPS10 +ms.date: 09/17/2024 +PlatyPS schema version: 2024-05-01 +title: Import-MarkdownModuleFile +--- + +# Import-MarkdownModuleFile + +## SYNOPSIS + +Imports a Markdown module file into a **ModuleHelp** object. + +## SYNTAX + +### Path (Default) + +``` +Import-MarkdownModuleFile [-Path] [] +``` + +### LiteralPath + +``` +Import-MarkdownModuleFile -LiteralPath [] +``` + +## ALIASES + +## DESCRIPTION + +The command imports Markdown files containing module help and creates **ModuleHelp** objects. The +**ModuleHelp** object is a structured representation of the help content that can be used to export +to different formats. + +## EXAMPLES + +### Example 1 - Convert + +```powershell +Import-MarkdownModuleFile .\v2\Microsoft.PowerShell.PlatyPS\Microsoft.PowerShell.PlatyPS.md +``` + +```Output +Metadata : {[document type, module], [HelpInfoUri, ], [Locale, en-US], [Module Guid, + 0bdcabef-a4b7-4a6d-bf7e-d879817ebbff]…} +Title : Microsoft.PowerShell.PlatyPS Module +Module : Microsoft.PowerShell.PlatyPS +ModuleGuid : 0bdcabef-a4b7-4a6d-bf7e-d879817ebbff +Description : This module contains cmdlets to help with the creation help content for PowerShell commands. +Locale : en-US +CommandGroups : {Microsoft.PowerShell.PlatyPS.ModuleCommandGroup} +Diagnostics : Microsoft.PowerShell.PlatyPS.Model.Diagnostics +``` + +## PARAMETERS + +### -LiteralPath + +Specifies a path to one or more locations containing markdown files. The value of **LiteralPath** is +used exactly as it's typed. No characters are interpreted as wildcards. If the path includes escape +characters, enclose it in single quotation marks. Single quotation marks tell PowerShell not to +interpret any characters as escape sequences. + +For more information, see +[about_Quoting_Rules](/powershell/module/microsoft.powershell.core/about/about_CommonParameters). + +```yaml +Type: System.String[] +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: [] +ParameterSets: +- Name: LiteralPath + Position: Named + IsRequired: true + ValueFromPipeline: true + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -Path + +Specifies the path to an item. This cmdlet gets the item at the specified location. Wildcard +characters are permitted. This parameter is required, but the parameter name Path is optional. + +Use a dot (`.`) to specify the current location. Use the wildcard character (`*`) to specify all +items in the current location. + +```yaml +Type: System.String[] +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: [] +ParameterSets: +- Name: Path + Position: 0 + IsRequired: true + ValueFromPipeline: true + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, +-ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### System.String + +## OUTPUTS + +### Microsoft.PowerShell.PlatyPS.ModuleFileInfo + +## NOTES + +## RELATED LINKS + +- [Export-MarkdownModuleFile](Export-MarkdownModuleFile.md) +- [Export-YamlModuleFile](Export-YamlModuleFile.md) +- [Import-MarkdownModuleFile](Import-MarkdownModuleFile.md) diff --git a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Import-YamlCommandHelp.md b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Import-YamlCommandHelp.md new file mode 100644 index 00000000..c32d30fa --- /dev/null +++ b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Import-YamlCommandHelp.md @@ -0,0 +1,177 @@ +--- +document type: cmdlet +external help file: Microsoft.PowerShell.PlatyPS.dll-Help.xml +HelpUri: '' +Locale: en-US +Module Name: Microsoft.PowerShell.PlatyPS +ms.custom: OPS10 +ms.date: 09/17/2024 +PlatyPS schema version: 2024-05-01 +title: Import-YamlCommandHelp +--- + +# Import-YamlCommandHelp + +## SYNOPSIS + +Imports Yaml help content into **CommandHelp** objects. + +## SYNTAX + +### Path (Default) + +``` +Import-YamlCommandHelp [-Path] [-AsDictionary] [] +``` + +### LiteralPath + +``` +Import-YamlCommandHelp -LiteralPath [-AsDictionary] [] +``` + +## ALIASES + +## DESCRIPTION + +The command imports Yaml files containing command help and creates **CommandHelp** objects. The +**CommandHelp** object is a structured representation of the help content that can be used to export +to different formats. + +## EXAMPLES + +### Example 1 - Import all cmdlet Yaml files in a folder + +The following example import cmdlet Markdown files in a folder and converts them to **CommandHelp** +objects. These objects can be used to export to different formats. + +```powershell +Import-YamlCommandHelp -Path .\v2\yaml\*-*.yml | Select-Object Title +``` + +```Output +Title +----- +Compare-CommandHelp +Export-MamlCommandHelp +Export-MarkdownCommandHelp +Export-MarkdownModuleFile +Export-YamlCommandHelp +Export-YamlModuleFile +Import-MamlHelp +Import-MarkdownCommandHelp +Import-MarkdownModuleFile +Import-YamlCommandHelp +Import-YamlModuleFile +Measure-PlatyPSMarkdown +New-CommandHelp +New-MarkdownCommandHelp +New-MarkdownModuleFile +Test-MarkdownCommandHelp +Update-CommandHelp +Update-MarkdownCommandHelp +Update-MarkdownModuleFile +``` + +## PARAMETERS + +### -AsDictionary + +By default this cmdlet returns **CommandHelp** objects. When you use this parameter. the cmdlet +returns the same information as an **OrderedDictionary** object. + +```yaml +Type: System.Management.Automation.SwitchParameter +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: [] +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -LiteralPath + +Specifies a path to one or more Yaml command files. The value of LiteralPath is used exactly as it's +typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose +it in single quotation marks. Single quotation marks tell PowerShell not to interpret any characters +as escape sequences. + +For more information, see +[about_Quoting_Rules](/powershell/module/microsoft.powershell.core/about/about_quoting_rules). + +```yaml +Type: System.String[] +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: [] +ParameterSets: +- Name: LiteralPath + Position: Named + IsRequired: true + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -Path + +The path to the Yaml command file. Specifies a path to one or more locations. + +```yaml +Type: System.String[] +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: +- FullName +ParameterSets: +- Name: Path + Position: 0 + IsRequired: true + ValueFromPipeline: true + ValueFromPipelineByPropertyName: true + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, +-ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### System.String + +## OUTPUTS + +### System.Collections.Specialized.OrderedDictionary + +This cmdlet returns an **OrderedDictionary** object when you use the **AsDictionary** parameter. + +### Microsoft.PowerShell.PlatyPS.Model.CommandHelp + +By default, this cmdlet returns **CommandHelp** objects. + +## NOTES + +## RELATED LINKS + +- [Export-YamlCommandHelp](Export-YamlCommandHelp.md) diff --git a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Import-YamlModuleFile.md b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Import-YamlModuleFile.md new file mode 100644 index 00000000..71caf997 --- /dev/null +++ b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Import-YamlModuleFile.md @@ -0,0 +1,155 @@ +--- +document type: cmdlet +external help file: Microsoft.PowerShell.PlatyPS.dll-Help.xml +HelpUri: '' +Locale: en-US +Module Name: Microsoft.PowerShell.PlatyPS +ms.custom: OPS10 +ms.date: 09/17/2024 +PlatyPS schema version: 2024-05-01 +title: Import-YamlModuleFile +--- + +# Import-YamlModuleFile + +## SYNOPSIS + +Imports a Yaml module file into a **ModuleHelp** object. + +## SYNTAX + +### Path (Default) + +``` +Import-YamlModuleFile [-Path] [-AsDictionary] [] +``` + +### LiteralPath + +``` +Import-YamlModuleFile -LiteralPath [-AsDictionary] [] +``` + +## ALIASES + +## DESCRIPTION + +The command imports Yaml files containing module help and creates **ModuleHelp** objects. The +**ModuleHelp** object is a structured representation of the help content that can be used to export +to different formats. + +## EXAMPLES + +### Example 1 - Import a Yaml module file to a **ModuleHelp** object + +```powershell +Import-YamlModuleFile .\v2\yaml\Microsoft.PowerShell.PlatyPS.yml +``` + +```Output +Metadata : {[document type, module], [HelpInfoUri, ], [Locale, en-US], [Module Guid, + 0bdcabef-a4b7-4a6d-bf7e-d879817ebbff]…} +Title : Microsoft.PowerShell.PlatyPS Module +Module : Microsoft.PowerShell.PlatyPS +ModuleGuid : 0bdcabef-a4b7-4a6d-bf7e-d879817ebbff +Description : This module contains cmdlets to help with the creation help content for PowerShell commands. +Locale : en-US +CommandGroups : {Microsoft.PowerShell.PlatyPS.ModuleCommandGroup} +Diagnostics : Microsoft.PowerShell.PlatyPS.Model.Diagnostics +``` + +## PARAMETERS + +### -AsDictionary + +By default, the command returns a **ModuleHelp** object. When you use this parameter, the command +returns the **ModuleHelp** data a dictionary object. + +```yaml +Type: System.Management.Automation.SwitchParameter +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: [] +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -LiteralPath + +Specifies a path to one or more Yaml module files. The value of **LiteralPath** is used exactly as +it's typed. No characters are interpreted as wildcards. If the path includes escape characters, +enclose it in single quotation marks. Single quotation marks tell PowerShell not to interpret any +characters as escape sequences. + +For more information, see +[about_Quoting_Rules](/powershell/module/microsoft.powershell.core/about/about_CommonParameters). + +```yaml +Type: System.String[] +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: [] +ParameterSets: +- Name: LiteralPath + Position: Named + IsRequired: true + ValueFromPipeline: true + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -Path + +Specifies a path to one or more locations containing Yaml module files. + +```yaml +Type: System.String[] +DefaultValue: '' +SupportsWildcards: true +ParameterValue: [] +Aliases: [] +ParameterSets: +- Name: Path + Position: 0 + IsRequired: true + ValueFromPipeline: true + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, +-ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### System.String + +## OUTPUTS + +### Microsoft.PowerShell.PlatyPS.ModuleFileInfo + +## NOTES + +## RELATED LINKS + +- [Import-MarkdownModuleFile](Import-MarkdownModuleFile.md) diff --git a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Measure-PlatyPSMarkdown.md b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Measure-PlatyPSMarkdown.md new file mode 100644 index 00000000..728d5de8 --- /dev/null +++ b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Measure-PlatyPSMarkdown.md @@ -0,0 +1,153 @@ +--- +document type: cmdlet +external help file: Microsoft.PowerShell.PlatyPS.dll-Help.xml +HelpUri: '' +Locale: en-US +Module Name: Microsoft.PowerShell.PlatyPS +ms.custom: OPS10 +ms.date: 09/17/2024 +PlatyPS schema version: 2024-05-01 +title: Measure-PlatyPSMarkdown +--- + +# Measure-PlatyPSMarkdown + +## SYNOPSIS + +Determines the type of Markdown file. + +## SYNTAX + +### Path (Default) + +``` +Measure-PlatyPSMarkdown [-Path] [] +``` + +### LiteralPath + +``` +Measure-PlatyPSMarkdown -LiteralPath [] +``` + +## ALIASES + +## DESCRIPTION + +The command reads the content of the file and determines the type of content. The command returns a +**PlatyPSMarkdown** object that contains the content type and schema version of a PlatyPS markdown +file. This is useful for selecting just the files that contain **CommandHelp** or **ModuleHelp** +content. + +## EXAMPLES + +### Example 1 - Measure all Markdown files in a folder + +```powershell +Measure-PlatyPSMarkdown -Path .\v2\Microsoft.PowerShell.PlatyPS\*.md +``` + +```Output +Title Filetype Filepath +----- -------- -------- +Compare-CommandHelp CommandHelp, V2Schema D:\Git\PS-Src\platyPS\v2docs\v2\Microsoft.PowerShell.PlatyPS\Compare-CommandHelp.md +Export-MamlCommandHelp CommandHelp, V2Schema D:\Git\PS-Src\platyPS\v2docs\v2\Microsoft.PowerShell.PlatyPS\Export-MamlCommandHelp.md +Export-MarkdownCommandHelp CommandHelp, V2Schema D:\Git\PS-Src\platyPS\v2docs\v2\Microsoft.PowerShell.PlatyPS\Export-MarkdownCommandHelp.md +Export-MarkdownModuleFile CommandHelp, V2Schema D:\Git\PS-Src\platyPS\v2docs\v2\Microsoft.PowerShell.PlatyPS\Export-MarkdownModuleFile.md +Export-YamlCommandHelp CommandHelp, V2Schema D:\Git\PS-Src\platyPS\v2docs\v2\Microsoft.PowerShell.PlatyPS\Export-YamlCommandHelp.md +Export-YamlModuleFile CommandHelp, V2Schema D:\Git\PS-Src\platyPS\v2docs\v2\Microsoft.PowerShell.PlatyPS\Export-YamlModuleFile.md +Import-MamlHelp CommandHelp, V2Schema D:\Git\PS-Src\platyPS\v2docs\v2\Microsoft.PowerShell.PlatyPS\Import-MamlHelp.md +Import-MarkdownCommandHelp CommandHelp, V2Schema D:\Git\PS-Src\platyPS\v2docs\v2\Microsoft.PowerShell.PlatyPS\Import-MarkdownCommandHelp.md +Import-MarkdownModuleFile CommandHelp, V2Schema D:\Git\PS-Src\platyPS\v2docs\v2\Microsoft.PowerShell.PlatyPS\Import-MarkdownModuleFile.md +Import-YamlCommandHelp CommandHelp, V2Schema D:\Git\PS-Src\platyPS\v2docs\v2\Microsoft.PowerShell.PlatyPS\Import-YamlCommandHelp.md +Import-YamlModuleFile CommandHelp, V2Schema D:\Git\PS-Src\platyPS\v2docs\v2\Microsoft.PowerShell.PlatyPS\Import-YamlModuleFile.md +Measure-PlatyPSMarkdown CommandHelp, V2Schema D:\Git\PS-Src\platyPS\v2docs\v2\Microsoft.PowerShell.PlatyPS\Measure-PlatyPSMarkdown.md +Microsoft.PowerShell.PlatyPS Module ModuleFile, V2Schema D:\Git\PS-Src\platyPS\v2docs\v2\Microsoft.PowerShell.PlatyPS\Microsoft.PowerShell.PlatyPS.md +New-CommandHelp CommandHelp, V2Schema D:\Git\PS-Src\platyPS\v2docs\v2\Microsoft.PowerShell.PlatyPS\New-CommandHelp.md +New-MarkdownCommandHelp CommandHelp, V2Schema D:\Git\PS-Src\platyPS\v2docs\v2\Microsoft.PowerShell.PlatyPS\New-MarkdownCommandHelp.md +New-MarkdownModuleFile CommandHelp, V2Schema D:\Git\PS-Src\platyPS\v2docs\v2\Microsoft.PowerShell.PlatyPS\New-MarkdownModuleFile.md +Test-MarkdownCommandHelp CommandHelp, V2Schema D:\Git\PS-Src\platyPS\v2docs\v2\Microsoft.PowerShell.PlatyPS\Test-MarkdownCommandHelp.md +Update-CommandHelp CommandHelp, V2Schema D:\Git\PS-Src\platyPS\v2docs\v2\Microsoft.PowerShell.PlatyPS\Update-CommandHelp.md +Update-MarkdownCommandHelp CommandHelp, V2Schema D:\Git\PS-Src\platyPS\v2docs\v2\Microsoft.PowerShell.PlatyPS\Update-MarkdownCommandHelp.md +Update-MarkdownModuleFile CommandHelp, V2Schema D:\Git\PS-Src\platyPS\v2docs\v2\Microsoft.PowerShell.PlatyPS\Update-MarkdownModuleFile.md +``` + +## PARAMETERS + +### -LiteralPath + +Specifies a path to one or more Markdown files. The value of **LiteralPath** is used exactly as it's +typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose +it in single quotation marks. Single quotation marks tell PowerShell not to interpret any characters +as escape sequences. + +For more information, see +[about_Quoting_Rules](/powershell/module/microsoft.powershell.core/about/about_quoting_rules). + +```yaml +Type: System.String[] +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: [] +ParameterSets: +- Name: LiteralPath + Position: Named + IsRequired: true + ValueFromPipeline: true + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -Path + +The path to one or more Markdown files. Specifies a path to one or more locations. + +```yaml +Type: System.String[] +DefaultValue: '' +SupportsWildcards: true +ParameterValue: [] +Aliases: [] +ParameterSets: +- Name: Path + Position: 0 + IsRequired: true + ValueFromPipeline: true + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, +-ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### System.String + +## OUTPUTS + +### Microsoft.PowerShell.PlatyPS.MarkdownProbeInfo + +## NOTES + +For old format markdown files, the command examines the frontmatter and H2 structure to determine +the content type. For new format markdown files, the command examines the `document type` key in the +frontmatter. + +The command doesn't validate the full structure of the markdown file. Use `Test-MarkdownCommandHelp` +to validate the structure of the markdown file. + +## RELATED LINKS + +- [Test-MarkdownCommandHelp](Test-MarkdownCommandHelp.md) diff --git a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Microsoft.PowerShell.PlatyPS.md b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Microsoft.PowerShell.PlatyPS.md new file mode 100644 index 00000000..1a79188e --- /dev/null +++ b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Microsoft.PowerShell.PlatyPS.md @@ -0,0 +1,97 @@ +--- +document type: module +HelpInfoUri: '' +Locale: en-US +Module Guid: 0bdcabef-a4b7-4a6d-bf7e-d879817ebbff +Module Name: Microsoft.PowerShell.PlatyPS +ms.custom: OPS10 +ms.date: 09/18/2024 +PlatyPS schema version: 2024-05-01 +title: Microsoft.PowerShell.PlatyPS Module +--- + +# Microsoft.PowerShell.PlatyPS Module + +## Description + +This module contains cmdlets to help with the creation help content for PowerShell commands. + +## Microsoft.PowerShell.PlatyPS Cmdlets + +### [Compare-CommandHelp](Compare-CommandHelp.md) + +Compares two **CommandHelp** objects and produces a detailed report showing the differences. + +### [Export-MamlCommandHelp](Export-MamlCommandHelp.md) + +Exports **CommandHelp** objects to a MAML file. + +### [Export-MarkdownCommandHelp](Export-MarkdownCommandHelp.md) + +Exports a **CommandHelp** object to a markdown file. + +### [Export-MarkdownModuleFile](Export-MarkdownModuleFile.md) + +Exports a **ModuleFileInfo** object to a markdown file. + +### [Export-YamlCommandHelp](Export-YamlCommandHelp.md) + +Exports **CommandHelp** objects to YAML files. + +### [Export-YamlModuleFile](Export-YamlModuleFile.md) + +Exports a **ModuleFileInfo** object to a Yaml file. + +### [Import-MamlHelp](Import-MamlHelp.md) + +Imports MAML help from a file and creates **CommandHelp** objects for each command in the file. + +### [Import-MarkdownCommandHelp](Import-MarkdownCommandHelp.md) + +Imports Markdown help content into **CommandHelp** objects. + +### [Import-MarkdownModuleFile](Import-MarkdownModuleFile.md) + +Imports a Markdown module file into a **ModuleHelp** object. + +### [Import-YamlCommandHelp](Import-YamlCommandHelp.md) + +Imports Yaml help content into **CommandHelp** objects. + +### [Import-YamlModuleFile](Import-YamlModuleFile.md) + +Imports a Yaml module file into a **ModuleHelp** object. + +### [Measure-PlatyPSMarkdown](Measure-PlatyPSMarkdown.md) + +Determines the type of Markdown file. + +### [New-CommandHelp](New-CommandHelp.md) + +Creates **CommandHelp** objects for a PowerShell command that's loaded in the session. + +### [New-MarkdownCommandHelp](New-MarkdownCommandHelp.md) + +Creates Markdown help files for PowerShell modules and commands. + +### [New-MarkdownModuleFile](New-MarkdownModuleFile.md) + +Creates the Markdown module file for a PowerShell module. + +### [Test-MarkdownCommandHelp](Test-MarkdownCommandHelp.md) + +Tests the structure of a Markdown help file. + +### [Update-CommandHelp](Update-CommandHelp.md) + +Updates an imported **CommandHelp** object with the information from session cmdlet of the same +name. + +### [Update-MarkdownCommandHelp](Update-MarkdownCommandHelp.md) + +Updates an imported Markdown command file with the information from session cmdlet of the same name. + +### [Update-MarkdownModuleFile](Update-MarkdownModuleFile.md) + +Updates the Markdown module file. + diff --git a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/New-CommandHelp.md b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/New-CommandHelp.md new file mode 100644 index 00000000..5adea77b --- /dev/null +++ b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/New-CommandHelp.md @@ -0,0 +1,124 @@ +--- +document type: cmdlet +external help file: Microsoft.PowerShell.PlatyPS.dll-Help.xml +HelpUri: '' +Locale: en-US +Module Name: Microsoft.PowerShell.PlatyPS +ms.custom: OPS10 +ms.date: 09/17/2024 +PlatyPS schema version: 2024-05-01 +title: New-CommandHelp +--- + +# New-CommandHelp + +## SYNOPSIS + +Creates **CommandHelp** objects for a PowerShell command that's loaded in the session. + +## SYNTAX + +### __AllParameterSets + +``` +New-CommandHelp [-CommandInfo] [] +``` + +## ALIASES + +## DESCRIPTION + +This cmdlet takes a list of one or more PowerShell commands and creates **CommandHelp** objects for +each command. The **CommandHelp** object is a structured representation of the help content that can +be used to export to different formats. + +## EXAMPLES + +### Example 1 - Creates a **CommandHelp** object for a cmdlet + +The following example creates a **CommandHelp** object for the `New-PSSession` cmdlet. The +`Get-Member` cmdlet is used to display the properties and methods of the **CommandHelp** object. + +```powershell +New-CommandHelp New-PSSession | Get-Member +``` + +```Output + TypeName: Microsoft.PowerShell.PlatyPS.Model.CommandHelp + +Name MemberType Definition +---- ---------- ---------- +Equals Method bool Equals(Microsoft.PowerShell.PlatyPS.Model.CommandHelp other)... +GetHashCode Method int GetHashCode() +GetType Method type GetType() +ToString Method string ToString() +TryGetParameter Method bool TryGetParameter(string name, [ref] Microsoft.PowerShell.Plat... +Aliases Property System.Collections.Generic.List[string] Aliases {get;} +Description Property string Description {get;set;} +Diagnostics Property Microsoft.PowerShell.PlatyPS.Model.Diagnostics Diagnostics {get;s... +Examples Property System.Collections.Generic.List[Microsoft.PowerShell.PlatyPS.Mode... +ExternalHelpFile Property string ExternalHelpFile {get;set;} +HasCmdletBinding Property bool HasCmdletBinding {get;set;} +HasWorkflowCommonParameters Property bool HasWorkflowCommonParameters {get;set;} +Inputs Property System.Collections.Generic.List[Microsoft.PowerShell.PlatyPS.Mode... +Locale Property cultureinfo Locale {get;set;} +Metadata Property ordered Metadata {get;set;} +ModuleGuid Property System.Nullable[guid] ModuleGuid {get;set;} +ModuleName Property string ModuleName {get;set;} +Notes Property string Notes {get;set;} +OnlineVersionUrl Property string OnlineVersionUrl {get;set;} +Outputs Property System.Collections.Generic.List[Microsoft.PowerShell.PlatyPS.Mode... +Parameters Property System.Collections.Generic.List[Microsoft.PowerShell.PlatyPS.Mode... +RelatedLinks Property System.Collections.Generic.List[Microsoft.PowerShell.PlatyPS.Mode... +SchemaVersion Property string SchemaVersion {get;set;} +Synopsis Property string Synopsis {get;set;} +Syntax Property System.Collections.Generic.List[Microsoft.PowerShell.PlatyPS.Mode... +Title Property string Title {get;set;} +``` + +## PARAMETERS + +### -CommandInfo + +A list of one or more PowerShell commands (cmdlets, functions, scripts). The cmdlet creates a +**CommandHelp** object for each command. + +```yaml +Type: System.Management.Automation.CommandInfo[] +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: [] +ParameterSets: +- Name: (All) + Position: 0 + IsRequired: true + ValueFromPipeline: true + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, +-ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### System.Management.Automation.CommandInfo + +## OUTPUTS + +### Microsoft.PowerShell.PlatyPS.Model.CommandHelp + +## NOTES + +## RELATED LINKS + +- [Export-MarkdownCommandHelp](Export-MarkdownCommandHelp.md) +- [Export-YamlCommandHelp](Export-YamlCommandHelp.md) diff --git a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/New-MarkdownCommandHelp.md b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/New-MarkdownCommandHelp.md new file mode 100644 index 00000000..0635d996 --- /dev/null +++ b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/New-MarkdownCommandHelp.md @@ -0,0 +1,413 @@ +--- +document type: cmdlet +external help file: Microsoft.PowerShell.PlatyPS.dll-Help.xml +HelpUri: '' +Locale: en-US +Module Name: Microsoft.PowerShell.PlatyPS +ms.custom: OPS10 +ms.date: 09/17/2024 +PlatyPS schema version: 2024-05-01 +title: New-MarkdownCommandHelp +--- + +# New-MarkdownCommandHelp + +## SYNOPSIS + +Creates Markdown help files for PowerShell modules and commands. + +## SYNTAX + +### __AllParameterSets + +``` +New-MarkdownCommandHelp -OutputFolder [-CommandInfo ] [-Encoding ] + [-Force] [-HelpUri ] [-HelpInfoUri ] [-HelpVersion ] [-Locale ] + [-Metadata ] [-ModuleInfo ] [-WithModulePage] + [-AbbreviateParameterTypename] [-WhatIf] [-Confirm] [] +``` + +## ALIASES + +## DESCRIPTION + +Creates Markdown help files for PowerShell modules and commands. + +## EXAMPLES + +### Example 1 - Create Markdown help files for a module + +```powershell +$newMarkdownCommandHelpSplat = @{ + ModuleInfo = Get-Module Microsoft.PowerShell.PlatyPS + OutputFolder = '.' + HelpVersion = '1.0.0.0' + WithModulePage = $true +} +New-MarkdownCommandHelp @newMarkdownCommandHelpSplat +``` + +### Example 2 - Create Markdown help files from a list of commands + +```powershell +$newMarkdownCommandHelpSplat = @{ + CommandInfo = Get-Command -Module Microsoft.PowerShell.PlatyPS + OutputFolder = '.' + HelpVersion = '1.0.0.0' + WithModulePage = $true +} +New-MarkdownCommandHelp @newMarkdownCommandHelpSplat +``` + +## PARAMETERS + +### -AbbreviateParameterTypename + +By default, this command uses full type names in the parameter metadata and for the input and output +types. When you use this parameter, the cmdlet outputs short type names. + +```yaml +Type: System.Management.Automation.SwitchParameter +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: [] +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -CommandInfo + +A list of one or more commands to create help for. + +```yaml +Type: System.Management.Automation.CommandInfo[] +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: [] +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: true + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -Confirm + +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: System.Management.Automation.SwitchParameter +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: +- cf +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -Encoding + +The encoding used when creating the output files. If not specified, the cmdlet uses value specified +by `$OutputEncoding`. + +```yaml +Type: System.Text.Encoding +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: [] +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -Force + +By default, this command doesn't overwrite existing files. When you use this parameter, the cmdlet +overwrites existing files. + +```yaml +Type: System.Management.Automation.SwitchParameter +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: [] +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -HelpInfoUri + +This parameter allows you to specify the URI used for updateable help. By default, the cmdlet uses +the HelpInfoUri specified in the module manifest. + +```yaml +Type: System.String +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: [] +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -HelpUri + +This parameter allows you to specify the URI used for online help. By default, the cmdlet uses the +URI defined in the `[CmdletBinding()]` attribute for the command. + +```yaml +Type: System.String +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: [] +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -HelpVersion + +This parameter allows you to specify the version of the help. The default value is `1.0.0.0`. This +version is written to the `HelpInfo.xml` file that is used for updateable help. + +```yaml +Type: System.Version +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: [] +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -Locale + +This parameter allows you to specify the language locale for the help files. By default, the cmdlet +uses the current **CultureInfo**. Use the `Get-Culture` cmdlet to see the current culture settings +on your system. + +```yaml +Type: System.String +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: [] +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -Metadata + +The metadata to add to the frontmatter of the markdown file. The metadata is a hashtable where the +you specify the key and value pairs to add to the frontmatter. New key names are added to the +existing frontmatter. The values of existing keys are overwritten. You can't overwrite the values of +the `document type` or `PlatyPS schema version` keys. If these keys are present in the hashtable, +the cmdlet ignores the values and outputs a warning. + +```yaml +Type: System.Collections.Hashtable +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: [] +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -ModuleInfo + +A list of one or more modules to create help for. The cmdlet creates Markdown help files for all +commands in the module. The cmdlet creates a folder matching the name of the module in the output +location. All Markdown files are written to the module folder. + +```yaml +Type: System.Management.Automation.PSModuleInfo[] +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: [] +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: true + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -OutputFolder + +Specifies the location of where the Markdown help files are written. The cmdlet creates a folder for +each module being processed. If the target command isn't associated with a module, the cmdlet +creates a the Markdown file in the root of the output folder. + +```yaml +Type: System.String +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: [] +ParameterSets: +- Name: (All) + Position: Named + IsRequired: true + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -WhatIf + +Shows what would happen if the cmdlet runs. The cmdlet isn't run. + +```yaml +Type: System.Management.Automation.SwitchParameter +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: +- wi +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -WithModulePage + +By default, this cmdlet only creates Markdown files for commands. When you use this parameter, the +cmdlet creates a Markdown file for the module. This Markdown file contains a list of all commands in +the module and metadata used to create the HelpInfo.xml file. + +```yaml +Type: System.Management.Automation.SwitchParameter +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: [] +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, +-ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### System.Management.Automation.CommandInfo + +### System.Management.Automation.PSModuleInfo + +## OUTPUTS + +### System.IO.FileInfo + +## NOTES + +## RELATED LINKS + +- [Export-MarkdownCommandHelp](Export-MarkdownCommandHelp.md) diff --git a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/New-MarkdownModuleFile.md b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/New-MarkdownModuleFile.md new file mode 100644 index 00000000..42b55010 --- /dev/null +++ b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/New-MarkdownModuleFile.md @@ -0,0 +1,332 @@ +--- +document type: cmdlet +external help file: Microsoft.PowerShell.PlatyPS.dll-Help.xml +HelpUri: '' +Locale: en-US +Module Name: Microsoft.PowerShell.PlatyPS +ms.custom: OPS10 +ms.date: 09/17/2024 +PlatyPS schema version: 2024-05-01 +title: New-MarkdownModuleFile +--- + +# New-MarkdownModuleFile + +## SYNOPSIS + +Creates the Markdown module file for a PowerShell module. + +## SYNTAX + +### __AllParameterSets + +``` +New-MarkdownModuleFile -OutputFolder [-CommandHelp ] [-Encoding ] + [-Force] [-HelpUri ] [-HelpInfoUri ] [-HelpVersion ] [-Locale ] + [-Metadata ] [-WhatIf] [-Confirm] [] +``` + +## ALIASES + +## DESCRIPTION + +This command creates the Markdown module file for a PowerShell module. The module file contains the +module metadata and a list of all commands with their synopsis descriptions. This file can be used +as the module landing page in a documentation set. The module metadata is used to by +`Export-MamlCommandHelp` to create the MAML help file for the module. + +## EXAMPLES + +### Example 1 - Create a new module file from a folder of command help files + +```powershell +$mdfiles = Measure-PlatyPSMarkdown -Path .\v2\Microsoft.PowerShell.PlatyPS\*.md +$mdfiles | Where-Object Filetype -match 'CommandHelp' | + Import-MarkdownCommandHelp -Path {$_.FilePath} | + New-MarkdownModuleFile -OutputFolder .\v2 -Force +``` + +```Output + Directory: D:\Docs\v2\Microsoft.PowerShell.PlatyPS + +Mode LastWriteTime Length Name +---- ------------- ------ ---- +-a--- 9/18/2024 1:49 PM 2129 Microsoft.PowerShell.PlatyPS.md +``` + +### Example 2 - Create a new module file from a list of commands + +```powershell +$newMarkdownCommandHelpSplat = @{ + CommandHelp = Get-Command -Module Microsoft.PowerShell.PlatyPS | New-CommandHelp + OutputFolder = '.\new' + Force = $true +} +New-MarkdownModuleFile @newMarkdownCommandHelpSplat +``` + +```Output + Directory: D:\Docs\new\Microsoft.PowerShell.PlatyPS + +Mode LastWriteTime Length Name +---- ------------- ------ ---- +-a--- 9/18/2024 1:49 PM 2129 Microsoft.PowerShell.PlatyPS.md +``` + +## PARAMETERS + +### -CommandHelp + +The **CommandHelp** objects to be included in the module file. You can pass the **CommandHelp** +object on the pipeline or by using the **Command** parameter. + +```yaml +Type: Microsoft.PowerShell.PlatyPS.Model.CommandHelp[] +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: [] +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: true + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -Confirm + +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: System.Management.Automation.SwitchParameter +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: +- cf +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -Encoding + +The encoding used when creating the output files. If not specified, the cmdlet uses value specified +by `$OutputEncoding`. + +```yaml +Type: System.Text.Encoding +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: [] +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -Force + +By default, this command doesn't overwrite existing files. When you use this parameter, the cmdlet +overwrites existing files. + +```yaml +Type: System.Management.Automation.SwitchParameter +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: [] +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -HelpInfoUri + +This parameter allows you to specify the URI used for updateable help. By default, the cmdlet uses +the HelpInfoUri specified in the module manifest. + +```yaml +Type: System.String +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: [] +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -HelpVersion + +This parameter allows you to specify the version of the help. The default value is `1.0.0.0`. This +version is written to the `HelpInfo.xml` file that is used for updateable help. + +```yaml +Type: System.Version +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: [] +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -Locale + +This parameter allows you to specify the language locale for the help files. By default, the cmdlet +uses the current **CultureInfo**. Use the `Get-Culture` cmdlet to see the current culture settings +on your system. + +```yaml +Type: System.String +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: [] +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -Metadata + +The metadata to add to the frontmatter of the markdown file. The metadata is a hashtable where the +you specify the key and value pairs to add to the frontmatter. New key names are added to the +existing frontmatter. The values of existing keys are overwritten. You can't overwrite the values of +the `document type` or `PlatyPS schema version` keys. If these keys are present in the hashtable, +the cmdlet ignores the values and outputs a warning. + +```yaml +Type: System.Collections.Hashtable +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: [] +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -OutputFolder + +Specifies the location of where the Markdown module file is written. The cmdlet creates a folder for +each module based on the **CommandHelp** object being processed. + +```yaml +Type: System.String +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: [] +ParameterSets: +- Name: (All) + Position: Named + IsRequired: true + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -WhatIf + +Shows what would happen if the cmdlet runs. The cmdlet isn't run. + +```yaml +Type: System.Management.Automation.SwitchParameter +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: +- wi +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, +-ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### Microsoft.PowerShell.PlatyPS.Model.CommandHelp + +## OUTPUTS + +### System.IO.FileInfo + +## NOTES + +## RELATED LINKS + +- [Export-MarkdownModuleFile](Export-MarkdownModuleFile.md) +- [Update-MarkdownModuleFile](Update-MarkdownModuleFile.md) diff --git a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Test-MarkdownCommandHelp.md b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Test-MarkdownCommandHelp.md new file mode 100644 index 00000000..be845215 --- /dev/null +++ b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Test-MarkdownCommandHelp.md @@ -0,0 +1,177 @@ +--- +document type: cmdlet +external help file: Microsoft.PowerShell.PlatyPS.dll-Help.xml +HelpUri: '' +Locale: en-US +Module Name: Microsoft.PowerShell.PlatyPS +ms.custom: OPS10 +ms.date: 09/17/2024 +PlatyPS schema version: 2024-05-01 +title: Test-MarkdownCommandHelp +--- + +# Test-MarkdownCommandHelp + +## SYNOPSIS + +Tests the structure of a Markdown help file. + +## SYNTAX + +### __AllParameterSets + +``` +Test-MarkdownCommandHelp [-FullName] [-DetailView] [] +``` + +### Item + +``` +Test-MarkdownCommandHelp [-Path] [-DetailView] [] +``` + +### Literal + +``` +Test-MarkdownCommandHelp -LiteralPath [-DetailView] [] +``` + +## ALIASES + +## DESCRIPTION + +This command reads a Markdown help file and validates the structure of the help content by checking +for the presence of required elements in the proper order. The command returns `$true` if the file +passes validation. The **DetailView** parameter can be used to display more detailed validation +information. + +## EXAMPLES + +### Example 1 - Test a Markdown help file + +For this example, we test the structure of a Markdown Module help file. This test fails because the +command expects to test a Markdown Command help file. + +```powershell +Test-MarkdownCommandHelp .\v2\Microsoft.PowerShell.PlatyPS\Microsoft.PowerShell.PlatyPS.md -DetailView +``` + +The output shows the kind of information you can expect from the **DetailView** parameter. + +```Output +Test-MarkdownCommandHelp + Valid: False + File: D:\Git\PS-Src\platyPS\v2docs\v2\Microsoft.PowerShell.PlatyPS\Microsoft.PowerShell.PlatyPS.md + +Messages: + PASS: First element is a thematic break + FAIL: SYNOPSIS not found. + FAIL: SYNTAX not found. + FAIL: DESCRIPTION not found. + FAIL: EXAMPLES not found. + FAIL: PARAMETERS not found. + FAIL: INPUTS not found. + FAIL: OUTPUTS not found. + FAIL: NOTES not found. + FAIL: RELATED LINKS not found. +``` + +## PARAMETERS + +### -DetailView + +Instructs the command to output detailed validation information. + +```yaml +Type: System.Management.Automation.SwitchParameter +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: [] +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -LiteralPath + +Specifies a path to one or more command markdown files. The value of **LiteralPath** is used exactly +as it's typed. No characters are interpreted as wildcards. If the path includes escape characters, +enclose it in single quotation marks. Single quotation marks tell PowerShell not to interpret any +characters as escape sequences. + +For more information, see +[about_Quoting_Rules](/powershell/module/microsoft.powershell.core/about/about_CommonParameters). + +```yaml +Type: System.String[] +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: +- PSPath +- LP +ParameterSets: +- Name: Literal + Position: Named + IsRequired: true + ValueFromPipeline: false + ValueFromPipelineByPropertyName: true + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -Path + +The path to the Markdown help file to test. + +```yaml +Type: System.String[] +DefaultValue: '' +SupportsWildcards: true +ParameterValue: [] +Aliases: [] +ParameterSets: +- Name: Item + Position: 0 + IsRequired: true + ValueFromPipeline: true + ValueFromPipelineByPropertyName: true + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, +-ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### System.String + +## OUTPUTS + +### System.Boolean + +### Microsoft.PowerShell.PlatyPS.MarkdownCommandHelpValidationResult + +## NOTES + +## RELATED LINKS + +- [Export-MarkdownCommandHelp](Export-MarkdownCommandHelp.md) +- [New-MarkdownCommandHelp](New-MarkdownCommandHelp.md) diff --git a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Update-CommandHelp.md b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Update-CommandHelp.md new file mode 100644 index 00000000..cc1b32c4 --- /dev/null +++ b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Update-CommandHelp.md @@ -0,0 +1,177 @@ +--- +document type: cmdlet +external help file: Microsoft.PowerShell.PlatyPS.dll-Help.xml +HelpUri: '' +Locale: en-US +Module Name: Microsoft.PowerShell.PlatyPS +ms.custom: OPS10 +ms.date: 09/17/2024 +PlatyPS schema version: 2024-05-01 +title: Update-CommandHelp +--- + +# Update-CommandHelp + +## SYNOPSIS + +Updates an imported **CommandHelp** object with the information from session cmdlet of the same +name. + +## SYNTAX + +### Path (Default) + +``` +Update-CommandHelp [-Path] [-WhatIf] [-Confirm] [] +``` + +### LiteralPath + +``` +Update-CommandHelp -LiteralPath [-WhatIf] [-Confirm] [] +``` + +## ALIASES + +## DESCRIPTION + +This cmdlet imports a **CommandHelp** object from a Markdown file and updates the object with the +information from the session cmdlet of the same name. The updated object can then be re-exported to +update the source Markdown file. + +## EXAMPLES + +### Example 1 + +```powershell +$mdfiles = Measure-PlatyPSMarkdown -Path .\v1\Microsoft.PowerShell.PlatyPS\*.md +$cmdobj = $mdfiles | Where-Object Filetype -match 'CommandHelp' | + Update-CommandHelp -Path {$_.FilePath} +$cmdobj.count +``` + +```Output +19 +``` + +## PARAMETERS + +### -Confirm + +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: System.Management.Automation.SwitchParameter +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: +- cf +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -LiteralPath + +Specifies a path to one or more markdown command files. The value of **LiteralPath** is used exactly +as it's typed. No characters are interpreted as wildcards. If the path includes escape characters, +enclose it in single quotation marks. Single quotation marks tell PowerShell not to interpret any +characters as escape sequences. + +For more information, see +[about_Quoting_Rules](/powershell/module/microsoft.powershell.core/about/about_CommonParameters). + +```yaml +Type: System.String[] +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: [] +ParameterSets: +- Name: LiteralPath + Position: Named + IsRequired: true + ValueFromPipeline: true + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -Path + +Specifies the path to one or more Markdown command file. Wildcard characters are permitted. + +```yaml +Type: System.String[] +DefaultValue: '' +SupportsWildcards: true +ParameterValue: [] +Aliases: [] +ParameterSets: +- Name: Path + Position: 0 + IsRequired: true + ValueFromPipeline: true + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -WhatIf + +Shows what would happen if the cmdlet runs. The cmdlet isn't run. + +```yaml +Type: System.Management.Automation.SwitchParameter +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: +- wi +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, +-ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### System.String + +## OUTPUTS + +### Microsoft.PowerShell.PlatyPS.Model.CommandHelp + +## NOTES + +This command is similar to the `Update-MarkdownCommandHelp` cmdlet, but it updates the +**CommandHelp** object in memory instead of updating the source Markdown file. + +## RELATED LINKS + +- [Update-MarkdownCommandHelp](Update-MarkdownCommandHelp.md) diff --git a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Update-MarkdownCommandHelp.md b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Update-MarkdownCommandHelp.md new file mode 100644 index 00000000..9fcae77e --- /dev/null +++ b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Update-MarkdownCommandHelp.md @@ -0,0 +1,218 @@ +--- +document type: cmdlet +external help file: Microsoft.PowerShell.PlatyPS.dll-Help.xml +HelpUri: '' +Locale: en-US +Module Name: Microsoft.PowerShell.PlatyPS +ms.custom: OPS10 +ms.date: 09/17/2024 +PlatyPS schema version: 2024-05-01 +title: Update-MarkdownCommandHelp +--- + +# Update-MarkdownCommandHelp + +## SYNOPSIS + +Updates an imported Markdown command file with the information from session cmdlet of the same name. + +## SYNTAX + +### Path (Default) + +``` +Update-MarkdownCommandHelp [-Path] [-NoBackup] [-PassThru] [-WhatIf] [-Confirm] + [] +``` + +### LiteralPath + +``` +Update-MarkdownCommandHelp -LiteralPath [-NoBackup] [-PassThru] [-WhatIf] [-Confirm] + [] +``` + +## ALIASES + +## DESCRIPTION + +This cmdlet imports a **CommandHelp** object from a Markdown file and updates the object with the +information from the session cmdlet of the same name, then rewrites the Markdown file with the +updated information. + +## EXAMPLES + +### Example 1 + +```powershell +$mdfiles = Measure-PlatyPSMarkdown -Path .\v1\Microsoft.PowerShell.PlatyPS\*.md +$mdfiles | Where-Object Filetype -match 'CommandHelp' | + Update-MarkdownCommandHelp -Path {$_.FilePath} +``` + +## PARAMETERS + +### -Confirm + +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: System.Management.Automation.SwitchParameter +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: +- cf +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -LiteralPath + +Specifies a path to one or more markdown command files. The value of **LiteralPath** is used exactly +as it's typed. No characters are interpreted as wildcards. If the path includes escape characters, +enclose it in single quotation marks. Single quotation marks tell PowerShell not to interpret any +characters as escape sequences. + +For more information, see +[about_Quoting_Rules](/powershell/module/microsoft.powershell.core/about/about_CommonParameters). + +```yaml +Type: System.String[] +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: [] +ParameterSets: +- Name: LiteralPath + Position: Named + IsRequired: true + ValueFromPipeline: true + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -NoBackup + +By default, the cmdlet creates a backup of the original Markdown file before updating it. Use this +parameter to suppress the creation of the backup file. + +```yaml +Type: System.Management.Automation.SwitchParameter +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: [] +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -PassThru + +By default, this cmdlet doesn't generate any output. Use this parameter to return the updated file +object. + +```yaml +Type: System.Management.Automation.SwitchParameter +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: [] +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -Path + +Specifies the path to one or more Markdown command file. Wildcard characters are permitted. + +```yaml +Type: System.String[] +DefaultValue: '' +SupportsWildcards: true +ParameterValue: [] +Aliases: [] +ParameterSets: +- Name: Path + Position: 0 + IsRequired: true + ValueFromPipeline: true + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -WhatIf + +Shows what would happen if the cmdlet runs. The cmdlet isn't run. + +```yaml +Type: System.Management.Automation.SwitchParameter +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: +- wi +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, +-ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### System.String + +## OUTPUTS + +### System.IO.FileInfo + +## NOTES + +This command is similar to the `Update-CommandHelp` cmdlet, but it updates the source Markdown file. + +## RELATED LINKS + +- [Update-CommandHelp](Update-CommandHelp.md) diff --git a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Update-MarkdownModuleFile.md b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Update-MarkdownModuleFile.md new file mode 100644 index 00000000..267fda0d --- /dev/null +++ b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Update-MarkdownModuleFile.md @@ -0,0 +1,406 @@ +--- +document type: cmdlet +external help file: Microsoft.PowerShell.PlatyPS.dll-Help.xml +HelpUri: '' +Locale: en-US +Module Name: Microsoft.PowerShell.PlatyPS +ms.custom: OPS10 +ms.date: 09/17/2024 +PlatyPS schema version: 2024-05-01 +title: Update-MarkdownModuleFile +--- + +# Update-MarkdownModuleFile + +## SYNOPSIS + +Updates the Markdown module file. + +## SYNTAX + +### path + +``` +Update-MarkdownModuleFile [-Path] [-CommandHelp] [-Encoding ] + [-Force] [-HelpUri ] [-HelpInfoUri ] [-HelpVersion ] [-Locale ] + [-Metadata ] [-NoBackup] [-WhatIf] [-Confirm] [] +``` + +### literalpath + +``` +Update-MarkdownModuleFile [-CommandHelp] -LiteralPath + [-Encoding ] [-Force] [-HelpUri ] [-HelpInfoUri ] + [-HelpVersion ] [-Locale ] [-Metadata ] [-NoBackup] [-WhatIf] + [-Confirm] [] +``` + +## ALIASES + +## DESCRIPTION + +This cmdlet updates a Markdown module file with **CommandHelp** object information imported from +Markdown command files. + +## EXAMPLES + +### Example 1 - Update a module file from new command help files + +```powershell +$mdfiles = Measure-PlatyPSMarkdown -Path .\Microsoft.PowerShell.PlatyPS\*.md +$mdfiles | Where-Object Filetype -match 'CommandHelp' | + Import-MarkdownCommandHelp -Path {$_.FilePath} | + Update-MarkdownModuleFile -Path .\Microsoft.PowerShell.PlatyPS\Microsoft.PowerShell.PlatyPS.md +``` + +## PARAMETERS + +### -CommandHelp + +The **CommandHelp** objects to export. You can pass the **CommandHelp** object on the pipeline or by +using this parameter. + +```yaml +Type: Microsoft.PowerShell.PlatyPS.Model.CommandHelp[] +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: [] +ParameterSets: +- Name: (All) + Position: 1 + IsRequired: true + ValueFromPipeline: true + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -Confirm + +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: System.Management.Automation.SwitchParameter +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: +- cf +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -Encoding + +The encoding to use when writing the markdown file. If no value is specified, encoding defaults to +the value of the `$OutputEncoding` preference variable. + +```yaml +Type: System.Text.Encoding +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: [] +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -Force + +Use the **Force** parameter to overwrite the output file if it already exists. + +```yaml +Type: System.Management.Automation.SwitchParameter +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: [] +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -HelpInfoUri + +This parameter allows you to specify the URI used for updateable help. By default, the cmdlet uses +the HelpInfoUri specified in the module manifest. + +```yaml +Type: System.String +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: [] +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -HelpVersion + +This parameter allows you to specify the version of the help. The default value is `1.0.0.0`. This +version is written to the `HelpInfo.xml` file that is used for updateable help. + +```yaml +Type: System.Version +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: [] +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -LiteralPath + +Specifies a path to one or more module markdown files. The value of **LiteralPath** is used exactly +as it's typed. No characters are interpreted as wildcards. If the path includes escape characters, +enclose it in single quotation marks. Single quotation marks tell PowerShell not to interpret any +characters as escape sequences. + +For more information, see +[about_Quoting_Rules](/powershell/module/microsoft.powershell.core/about/about_CommonParameters). + +```yaml +Type: System.String +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: [] +ParameterSets: +- Name: literalpath + Position: Named + IsRequired: true + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -Locale + +This parameter allows you to specify the language locale for the help files. By default, the cmdlet +uses the current **CultureInfo**. Use the `Get-Culture` cmdlet to see the current culture settings +on your system. + +```yaml +Type: System.String +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: [] +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -Metadata + +The metadata to add to the frontmatter of the markdown file. The metadata is a hashtable where the +you specify the key and value pairs to add to the frontmatter. New key names are added to the +existing frontmatter. The values of existing keys are overwritten. You can't overwrite the values of +the `document type` or `PlatyPS schema version` keys. If these keys are present in the hashtable, +the cmdlet ignores the values and outputs a warning. + +```yaml +Type: System.Collections.Hashtable +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: [] +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -ModuleFile + +A **ModuleFileInfo** object that represents the module to update. This can be imported from the +existing Markdown module file. + +```yaml +Type: Microsoft.PowerShell.PlatyPS.ModuleFileInfo +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: [] +ParameterSets: +- Name: (All) + Position: 0 + IsRequired: true + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -NoBackup + +By default, the cmdlet creates a backup of the original Markdown file before updating it. Use this +parameter to suppress the creation of the backup file. + +```yaml +Type: System.Management.Automation.SwitchParameter +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: [] +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -OutputFolder + +Specifies the location of where the Markdown module file is written. The cmdlet creates a folder for +each module based on the **CommandHelp** object being processed. + +```yaml +Type: System.String +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: [] +ParameterSets: +- Name: (All) + Position: Named + IsRequired: true + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -Path + +Specifies a path to one or more module markdown files. + +```yaml +Type: System.String +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: [] +ParameterSets: +- Name: path + Position: 0 + IsRequired: true + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -WhatIf + +Shows what would happen if the cmdlet runs. The cmdlet isn't run. + +```yaml +Type: System.Management.Automation.SwitchParameter +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: +- wi +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, +-ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### Microsoft.PowerShell.PlatyPS.Model.CommandHelp + +## OUTPUTS + +### System.IO.FileInfo + +## NOTES + +## RELATED LINKS + +- [New-MarkdownModuleFile](New-MarkdownModuleFile.md) diff --git a/docs/Get-HelpPreview.md b/docs/cmdlet-reference/platyPS/Get-HelpPreview.md similarity index 100% rename from docs/Get-HelpPreview.md rename to docs/cmdlet-reference/platyPS/Get-HelpPreview.md diff --git a/docs/Get-MarkdownMetadata.md b/docs/cmdlet-reference/platyPS/Get-MarkdownMetadata.md similarity index 100% rename from docs/Get-MarkdownMetadata.md rename to docs/cmdlet-reference/platyPS/Get-MarkdownMetadata.md diff --git a/docs/Merge-MarkdownHelp.md b/docs/cmdlet-reference/platyPS/Merge-MarkdownHelp.md similarity index 100% rename from docs/Merge-MarkdownHelp.md rename to docs/cmdlet-reference/platyPS/Merge-MarkdownHelp.md diff --git a/docs/New-ExternalHelp.md b/docs/cmdlet-reference/platyPS/New-ExternalHelp.md similarity index 100% rename from docs/New-ExternalHelp.md rename to docs/cmdlet-reference/platyPS/New-ExternalHelp.md diff --git a/docs/New-ExternalHelpCab.md b/docs/cmdlet-reference/platyPS/New-ExternalHelpCab.md similarity index 100% rename from docs/New-ExternalHelpCab.md rename to docs/cmdlet-reference/platyPS/New-ExternalHelpCab.md diff --git a/docs/New-MarkdownAboutHelp.md b/docs/cmdlet-reference/platyPS/New-MarkdownAboutHelp.md similarity index 100% rename from docs/New-MarkdownAboutHelp.md rename to docs/cmdlet-reference/platyPS/New-MarkdownAboutHelp.md diff --git a/docs/New-MarkdownHelp.md b/docs/cmdlet-reference/platyPS/New-MarkdownHelp.md similarity index 100% rename from docs/New-MarkdownHelp.md rename to docs/cmdlet-reference/platyPS/New-MarkdownHelp.md diff --git a/docs/New-YamlHelp.md b/docs/cmdlet-reference/platyPS/New-YamlHelp.md similarity index 100% rename from docs/New-YamlHelp.md rename to docs/cmdlet-reference/platyPS/New-YamlHelp.md diff --git a/docs/Update-MarkdownHelp.md b/docs/cmdlet-reference/platyPS/Update-MarkdownHelp.md similarity index 100% rename from docs/Update-MarkdownHelp.md rename to docs/cmdlet-reference/platyPS/Update-MarkdownHelp.md diff --git a/docs/Update-MarkdownHelpModule.md b/docs/cmdlet-reference/platyPS/Update-MarkdownHelpModule.md similarity index 100% rename from docs/Update-MarkdownHelpModule.md rename to docs/cmdlet-reference/platyPS/Update-MarkdownHelpModule.md diff --git a/docs/about_platyPS.md b/docs/cmdlet-reference/platyPS/about_platyPS.md similarity index 100% rename from docs/about_platyPS.md rename to docs/cmdlet-reference/platyPS/about_platyPS.md diff --git a/docs/developer/Microsoft.PowerShell.PlatyPS/CONTRIBUTING.md b/docs/developer/Microsoft.PowerShell.PlatyPS/CONTRIBUTING.md new file mode 100644 index 00000000..0e9a5bee --- /dev/null +++ b/docs/developer/Microsoft.PowerShell.PlatyPS/CONTRIBUTING.md @@ -0,0 +1,53 @@ +# Contributing to platyPS + +## Get the code + +``` +git clone https://github.com/PowerShell/platyPS +``` + +## Understand code layout + +TBD + +## Build + +To build the whole project, use the `build.ps1` helper script. It depends on the +[dotnet cli](https://docs.microsoft.com/en-us/dotnet/core/tools/) build tool. + +On Windows you would also need to +[install full dotnet framework](https://docs.microsoft.com/en-us/dotnet/framework/install/guide-for-developers) +if it's not installed already. + +```powershell +.\build.ps1 +``` + +As part of the build, platyPS generates help for itself. The output of the build is placed in +`out\Microsoft.PowerShell.PlatyPS`. + +`build.ps1` also imports the module from `out\platyPS` and generates help itself. + +> [!NOTE] +> If you changed C# code, `build.ps1` will try to overwrite a DLL in use. You will then need to +> re-open your PowerShell session. If you know a better workflow, please suggest it in the Issues. + +## Tests + +Each part of the project has a test set: + +- The C# part has xUnit tests. +- The PowerShell part has [Pester](https://github.com/pester/Pester) tests. You can run them with + `Invoke-Pester`. + +> [!NOTE] +> Pester tests always force-import the module from the output location of `.\build.ps1`. + +## Schema + +If you have ideas or concerns about the Markdown schema, feel free to open a GitHub Issue to discuss +it. + +## Repo structure + +TBD diff --git a/docs/developer/Microsoft.PowerShell.PlatyPS/specs/PlatyPS-Design-Notes.md b/docs/developer/Microsoft.PowerShell.PlatyPS/specs/PlatyPS-Design-Notes.md new file mode 100644 index 00000000..4c0cc2ce --- /dev/null +++ b/docs/developer/Microsoft.PowerShell.PlatyPS/specs/PlatyPS-Design-Notes.md @@ -0,0 +1,147 @@ +--- +ms.date: 10/22/2024 +--- +# Microsoft.PowerShell.PlatyPS design notes + +## Design notes + +### Features/Functionality + +- When PlatyPS writes file output, it should create folder structure of module-named folders + containing cmdlet markdown for the cmdlets in those modules +- PlatyPS should populate the markdown with all the facts that it can reasonably gather about the + command: + - Name + - Syntax of all parameter sets + - Parameter names and metadata (type, all attributes, etc. arranged by parameter set) + - Common parameters (if supported) + - Input types - types that can be piped to the command + - Output types - as defined by the cmdlet attributes +- PlatyPS should insert placeholder text for all content that must be provided by the author + +### Module notes + +- Total rewrite in C# to improve performance, object model, and extensibility + - Cmdlets are focused on the object model and provide a single purpose + - Chain cmdlets in a pipeline to perform complex operations + - Workflow style cmdlets will be script-based to improve usability for authors + - Script-based provide readable code model that allows end-users to customize their own + workflows as needed + - Workflows are easier to code in script rather than in C# +- Total breaking change from previous versions +- New module name - Microsoft.PowerShell.PlatyPS + - Allows you to install side-by-side with previous versions + - No common cmdlet names between modules + - No intent to provide proxies for old cmdlets +- Cmdlet names better reflect what they do + - Import-SomeFormat + - Export-SomeFormat +- New markdown parsing and rendering powered by markdig +- Module provides Yaml output to be used by the Learn reference pipeline +- Object model is the heart of the new module + - Establishes a common object model for cmdlets and module files + - Markdown is the source of truth for the documentation + - Cmdlets import the markdown in the the CommandHelp object model + - CommandHelp objects can be exported to Markdown, Yaml, or MAML + - CommandHelp objects can be imported from Markdown, Yaml, or MAML + - Conversion to/from MAML is lower fidelity other formats - results in loss of data and accuracy + of the documentation + +### Markdown notes + +- Markdown is the source of truth for the documentation +- Markdown has a strict H2/H3 structure + - You can't add headers or reorder them + - Not all H2/H3 sections require content. The H2/H3 line is required, but the content is optional. + This is done to ensure that the markdown structure is consistent with the object model. +- Metadata names have been changed to match PowerShell property names and common terminology. + - This causes less confusion for authors and makes it easier to troubleshoot validation and + rendering issues +- Import command can read old (0.14) format or new format and converts Markdown into CommandHelp + object +- Export commands convert CommandHelp object into other formats + - Export to markdown command can writes new markdown format + - Export to Yaml is used by the Learn reference pipeline and reflects the new object model + - Export to MAML is lower fidelity and results in loss of data and accuracy of the documentation + due to limitation in Get-Help and the MAML specification +- The Yaml frontmatter is used to store metadata that is not part of the markdown content + - The object model has a set of required key/value pairs + - The `document type` and `PlatyPS schema version` keys are inviolate (cannot be changed) + - You can add custom metadata to the frontmatter + - Any key/value pairs not managed by PlatyPS are passed through unaltered + +### Authoring process + +- Authoring is always a manual process requiring human intervention +- PlatyPS helps automate the process and provides a consistent structure for the documentation but + can't fill in descriptions, examples, or related links + - PlatyPS inserts placeholder text to show you where to add content +- Authors must review and edit the markdown files to ensure that the content is accurate for every + authoring step + - Creating new markdown for new modules/commands + - Migrating existing markdown to the new format + - Updating existing markdown based on new versions of modules/commands + +### Converting to/from other formats + +- Markdown is the source of truth for the documentation +- Converting from the old Markdown format to the new format is a one-way process + - The new format has more structure and metadata than the old format + - The new format is more consistent and easier to validate + - The old format does not reflect all of the correct facts about parameters + - Converting from the old to the new format does not improve the accuracy of the parameter + metadata; you must run the update process +- The update process requires that the commands/modules be available in the current session so + that the complete parameter metadata can be discovered +- Converting to Yaml + - There is no loss of fidelity when converting from the Markdown to Yaml (or vice versa) + - The Yaml is just a serialization of the CommandHelp object model + - All properties are preserved even if the value is null + - Rendering to HTML should handle null values gracefully (e.g. conditional formatting to omit null + values) +- Converting to/from MAML + - There is a loss of fidelity when converting to MAML due to limitations in the MAML specification + and Get-Help cmdlet +- Importing from MAML is supported as a method of last resort. + +## Frontmatter + +| FileType | v1 Key | v1 Status | v2 key | v2 Status | +|----------|--------------------|-----------------------------------------------------|------------------------|----------------------------------------------------| +| cmdlet | | n/a | document type | Required | +| cmdlet | external help file | Required - unique to cmdlet | external help file | Required | +| cmdlet | online version | Key required, value can be null - unique to cmdlet | HelpUri | Key required, value can be null - unique to cmdlet | +| cmdlet | Locale | Required | Locale | Required | +| cmdlet | Module Name | Key required, value can be null | Module Name | Key required, value can be null | +| cmdlet | ms.date | Optional | ms.date | Optional | +| cmdlet | schema | Required | PlatyPS schema version | Required | +| cmdlet | title | Required | title | Required | +| cmdlet | | n/a | aliases | Optional | +| module | | n/a | document type | Required | +| module | Help Version | Key required, value can be null - unique to module | Help Version | Key required, value can be null - unique to module | +| module | Download Help Link | Key required, value can be null - unique to module | HelpInfoUri | Key required, value can be null - unique to module | +| module | Locale | Required | Locale | Required | +| module | Module Guid | Required - unique to module | Module Guid | Required - unique to module | +| module | Module Name | Required | Module Name | Required | +| module | ms.date | Optional | ms.date | Optional | +| module | schema | Required | PlatyPS schema version | Required | +| module | title | Required | title | Required | + +## Scenarios to support OPS + +1. Workflow script to convert all markdown files to YAML in a folder +1. Workflow script for CabGen +1. Make rendering decisions for HTML presentation + +These items to be done by Sean and Jason working with DanniX and team. + +## Future ideas + +- Create a method to convert CommandHelp object to the Get-Help object model + - This could be an easy way to ship markdown instead of MAML for downlevel systems that don't have + or cant support Help v2. +- Add commands to stream conversion to Markdown to support Markdown rendering in the console (e.g. + pipe to `glow.exe`) +- Create workflow convenience scripts to include in module +- Compare-MarkdownCommandHelp - can't compare module files + diff --git a/specs/PowerShellCmdlet.schema.json b/docs/developer/Microsoft.PowerShell.PlatyPS/specs/PowerShellCmdlet.schema.json similarity index 100% rename from specs/PowerShellCmdlet.schema.json rename to docs/developer/Microsoft.PowerShell.PlatyPS/specs/PowerShellCmdlet.schema.json diff --git a/specs/PowershellCmdletV2.schema.json b/docs/developer/Microsoft.PowerShell.PlatyPS/specs/PowershellCmdletV2.schema.json similarity index 100% rename from specs/PowershellCmdletV2.schema.json rename to docs/developer/Microsoft.PowerShell.PlatyPS/specs/PowershellCmdletV2.schema.json diff --git a/specs/Schema-Notes.md b/docs/developer/Microsoft.PowerShell.PlatyPS/specs/Schema-Notes.md similarity index 100% rename from specs/Schema-Notes.md rename to docs/developer/Microsoft.PowerShell.PlatyPS/specs/Schema-Notes.md diff --git a/specs/alias-prototype.md b/docs/developer/Microsoft.PowerShell.PlatyPS/specs/alias-prototype.md similarity index 100% rename from specs/alias-prototype.md rename to docs/developer/Microsoft.PowerShell.PlatyPS/specs/alias-prototype.md diff --git a/specs/platyps_2.0_about_schema.md b/docs/developer/Microsoft.PowerShell.PlatyPS/specs/platyps_2.0_about_schema.md similarity index 100% rename from specs/platyps_2.0_about_schema.md rename to docs/developer/Microsoft.PowerShell.PlatyPS/specs/platyps_2.0_about_schema.md diff --git a/specs/platyps_2.0_cmdlets.md b/docs/developer/Microsoft.PowerShell.PlatyPS/specs/platyps_2.0_cmdlets.md similarity index 100% rename from specs/platyps_2.0_cmdlets.md rename to docs/developer/Microsoft.PowerShell.PlatyPS/specs/platyps_2.0_cmdlets.md diff --git a/specs/platyps_2.0_update.md b/docs/developer/Microsoft.PowerShell.PlatyPS/specs/platyps_2.0_update.md similarity index 100% rename from specs/platyps_2.0_update.md rename to docs/developer/Microsoft.PowerShell.PlatyPS/specs/platyps_2.0_update.md diff --git a/CONTRIBUTING.md b/docs/developer/platyPS/CONTRIBUTING.md similarity index 56% rename from CONTRIBUTING.md rename to docs/developer/platyPS/CONTRIBUTING.md index acf23bba..c0a901cd 100644 --- a/CONTRIBUTING.md +++ b/docs/developer/platyPS/CONTRIBUTING.md @@ -10,61 +10,61 @@ git clone https://github.com/PowerShell/platyPS There are two parts: -- `Markdown.MAML.dll`, a .NET library written in C#. - It does the heavy lifting, like parsing Markdown, transforming it into XML, and so on. - You can open `.\Markdown.MAML.sln` in Visual Studio on any platform. -- A PowerShell module in `.\src\platyPS`. - This module provides the user CLI. +- `Markdown.MAML.dll`, a .NET library written in C#. It does the heavy lifting, like parsing + Markdown, transforming it into XML, and so on. You can open `.\Markdown.MAML.sln` in Visual Studio + on any platform. +- A PowerShell module in `.\src\platyPS`. This module provides the user CLI. ## Build -To build the whole project, use the `build.ps1` helper script. -It depends on the [dotnet cli](https://docs.microsoft.com/en-us/dotnet/core/tools/) build tool. +To build the whole project, use the `build.ps1` helper script. It depends on the [dotnet cli][01] +build tool. -On Windows you would also need to [install full dotnet framework](https://docs.microsoft.com/en-us/dotnet/framework/install/guide-for-developers) if it's not installed already. +On Windows you would also need to [install full dotnet framework][02] if it's not installed already. ```powershell .\build.ps1 ``` -As part of the build, platyPS generates help for itself. -The output of the build is placed in `out\platyPS`. + +As part of the build, platyPS generates help for itself. The output of the build is placed in +`out\Microsoft.PowerShell.PlatyPS`. `build.ps1` also imports the module from `out\platyPS` and generates help itself. -**Note**: if you changed C# code, `build.ps1` will try to overwrite a DLL in use. -You will then need to re-open your PowerShell session. -If you know a better workflow, please suggest it in the Issues. +> [!NOTE] +> If you changed C# code, `build.ps1` will try to overwrite a DLL in use. You will then need to +> re-open your PowerShell session. If you know a better workflow, please suggest it in the Issues. ## Tests Each part of the project has a test set: -- The C# part has xUnit tests. - You can run them from Visual Studio or from command line with `dotnet test ./test/Markdown.MAML.Test`. -- The PowerShell part has [Pester](https://github.com/pester/Pester) tests. - You can run them with `Invoke-Pester`. +- The C# part has xUnit tests. You can run them from Visual Studio or from command line with + `dotnet test ./test/Markdown.MAML.Test`. +- The PowerShell part has [Pester][03] tests. You can run them with `Invoke-Pester`. -**Note**: Pester tests always force-import the module from the output location of `.\build.ps1`. +> [!NOTE] +> Pester tests always force-import the module from the output location of `.\build.ps1`. ## Schema -If you have ideas or concerns about the Markdown schema, feel free to open a GitHub Issue to discuss it. +If you have ideas or concerns about the Markdown schema, feel free to open a GitHub Issue to discuss +it. ## Repo structure - **src\platyPS** - sources to create the final PowerShell module. - **src\Markdown.MAML, Markdown.MAML.sln** - source code for C# Markdown to MAML converter. -- **[platyPS.schema.md](platyPS.schema.md)** - description of Markdown that platyPS expects. +- **[platyPS.schema.md][04]** - description of Markdown that platyPS expects. ## Data transformations -Data transformations are the core of platyPS. -A user has content in some form and she wants to transform it into another form. -E.g. transform existing module help (in MAML) to Markdown and use it in the future to generate the external help (MAML) and static HTML for online references. +Data transformations are the core of platyPS. A user has content in some form and she wants to +transform it into another form. E.g. transform existing module help (in MAML) to Markdown and use it +in the future to generate the external help (MAML) and static HTML for online references. -platyPS provides APIs in the form of cmdlets for end-user scenarios. -These scenarios are assembled from simple transformations. -This chart describes these simple transformations: +platyPS provides APIs in the form of cmdlets for end-user scenarios. These scenarios are assembled +from simple transformations. This chart describes these simple transformations: ``` +----------+ @@ -106,21 +106,33 @@ New-MarkdownHelp -Command New-MyCommandHelp Under the hood, the following tranformations happen: +``` [MAML XML file] --> [Help Object + Get-Command object] --> [MAML Model] --> [Markdown file] +``` # Making a new release -1. Make sure that `CHANGELOG.md` is up-to-date, move section from `UNRELEASED` to new section ``. -1. Make sure platyPS help itself (content in .\docs folder) is up to date. +1. Make sure that `CHANGELOG.md` is up-to-date, move section from `UNRELEASED` to new section + ``. +1. Make sure platyPS help itself (content in .\docs folder) is up to date. `Update-MarkdownHelp -Path .\docs` should result in no changes. 1. Do not change the version in platyps.psd1. Git tag will update this version for release. 1. From master, tag the release. 1. Push tag to GitHub. 1. Find the corresponding build on AppVeyor. 1. Download ZIP archive with the module from Appveyor's Artifacts tab. -1. Unblock the ZIP archive (`Unblock-File foo.zip`), and copy the ZIP's contents to `$env:PSMODULEPATH` so it's available to `Publish-Module`. -1. Publish the module to the Gallery: `Publish-Module -RequiredVersion -Verbose -NuGetApiKey $apiKey`. +1. Unblock the ZIP archive (`Unblock-File foo.zip`), and copy the ZIP's contents to + `$env:PSMODULEPATH` so it's available to `Publish-Module`. +1. Publish the module to the Gallery: + `Publish-Module -RequiredVersion -Verbose -NuGetApiKey $apiKey`. 1. Check that https://www.powershellgallery.com/packages/platyPS/ updated. -1. Publish a new github release from https://github.com/PowerShell/platyPS/releases to move "Latest release" label to the new tag. +1. Publish a new github release from https://github.com/PowerShell/platyPS/releases to move "Latest + release" label to the new tag. Congratulations! You just made a release. + + +[01]: https://docs.microsoft.com/en-us/dotnet/core/tools/ +[02]: https://docs.microsoft.com/en-us/dotnet/framework/install/guide-for-developers +[03]: https://github.com/pester/Pester +[04]: platyPS.schema.md diff --git a/platyPS.schema.md b/docs/developer/platyPS/platyPS.schema.md similarity index 100% rename from platyPS.schema.md rename to docs/developer/platyPS/platyPS.schema.md diff --git a/presentation/css/impress-demo.css b/docs/developer/platyPS/presentation/css/impress-demo.css similarity index 100% rename from presentation/css/impress-demo.css rename to docs/developer/platyPS/presentation/css/impress-demo.css diff --git a/presentation/images/FFFUUU.png b/docs/developer/platyPS/presentation/images/FFFUUU.png similarity index 100% rename from presentation/images/FFFUUU.png rename to docs/developer/platyPS/presentation/images/FFFUUU.png diff --git a/presentation/images/azure-maml.png b/docs/developer/platyPS/presentation/images/azure-maml.png similarity index 100% rename from presentation/images/azure-maml.png rename to docs/developer/platyPS/presentation/images/azure-maml.png diff --git a/presentation/images/get-help.png b/docs/developer/platyPS/presentation/images/get-help.png similarity index 100% rename from presentation/images/get-help.png rename to docs/developer/platyPS/presentation/images/get-help.png diff --git a/presentation/images/markdown-github.png b/docs/developer/platyPS/presentation/images/markdown-github.png similarity index 100% rename from presentation/images/markdown-github.png rename to docs/developer/platyPS/presentation/images/markdown-github.png diff --git a/presentation/images/markdown.png b/docs/developer/platyPS/presentation/images/markdown.png similarity index 100% rename from presentation/images/markdown.png rename to docs/developer/platyPS/presentation/images/markdown.png diff --git a/presentation/images/pscmdlethelpeditor.png b/docs/developer/platyPS/presentation/images/pscmdlethelpeditor.png similarity index 100% rename from presentation/images/pscmdlethelpeditor.png rename to docs/developer/platyPS/presentation/images/pscmdlethelpeditor.png diff --git a/presentation/images/psreadline-maml.png b/docs/developer/platyPS/presentation/images/psreadline-maml.png similarity index 100% rename from presentation/images/psreadline-maml.png rename to docs/developer/platyPS/presentation/images/psreadline-maml.png diff --git a/presentation/index.html b/docs/developer/platyPS/presentation/index.html similarity index 100% rename from presentation/index.html rename to docs/developer/platyPS/presentation/index.html diff --git a/presentation/js/impress.js b/docs/developer/platyPS/presentation/js/impress.js similarity index 100% rename from presentation/js/impress.js rename to docs/developer/platyPS/presentation/js/impress.js From cfd5eafac01140dd733b2192ce41d66e09cf04c4 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Tue, 22 Oct 2024 14:09:37 -0500 Subject: [PATCH 24/27] Fix typo in link to schema doc --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 58a02fb2..e0f3ca2d 100644 --- a/README.md +++ b/README.md @@ -123,7 +123,7 @@ For any security issues, please see our [Security Policy][08]. [01]: CODE_OF_CONDUCT.md [02]: docs/developer/platyPS/CONTRIBUTING.md -[03]: docs/deveopler/platyPS.schema.md +[03]: docs/developer/platyPS/platyPS.schema.md [04]: https://code.visualstudio.com/ [05]: https://docs.microsoft.com/powershell/module/microsoft.powershell.utility/import-pssession [06]: https://learn.microsoft.com/powershell/module/platyps/ From a5cc2b9a547721b365689b3c457896dac94d35c8 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Sat, 26 Oct 2024 13:20:48 -0500 Subject: [PATCH 25/27] Update cmdlet docs for OPS13 --- .../Compare-CommandHelp.md | 4 +- .../Export-MamlCommandHelp.md | 4 +- .../Export-MarkdownCommandHelp.md | 4 +- .../Export-MarkdownModuleFile.md | 4 +- .../Export-YamlCommandHelp.md | 4 +- .../Export-YamlModuleFile.md | 4 +- .../Import-MamlHelp.md | 6 +- .../Import-MarkdownCommandHelp.md | 6 +- .../Import-MarkdownModuleFile.md | 6 +- .../Import-YamlCommandHelp.md | 6 +- .../Import-YamlModuleFile.md | 4 +- .../Measure-PlatyPSMarkdown.md | 4 +- .../Microsoft.PowerShell.PlatyPS.md | 15 +- .../New-CommandHelp.md | 4 +- .../New-HelpCabinetFile.md | 188 ++++++++++++++++++ .../New-MarkdownCommandHelp.md | 4 +- .../New-MarkdownModuleFile.md | 26 ++- .../Show-HelpPreview.md | 172 ++++++++++++++++ .../Test-MarkdownCommandHelp.md | 10 +- .../Update-CommandHelp.md | 4 +- .../Update-MarkdownCommandHelp.md | 4 +- .../Update-MarkdownModuleFile.md | 72 +++---- 22 files changed, 458 insertions(+), 97 deletions(-) create mode 100644 docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/New-HelpCabinetFile.md create mode 100644 docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Show-HelpPreview.md diff --git a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Compare-CommandHelp.md b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Compare-CommandHelp.md index 4eb024dc..5ce78eac 100644 --- a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Compare-CommandHelp.md +++ b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Compare-CommandHelp.md @@ -4,8 +4,8 @@ external help file: Microsoft.PowerShell.PlatyPS.dll-Help.xml HelpUri: '' Locale: en-US Module Name: Microsoft.PowerShell.PlatyPS -ms.custom: OPS10 -ms.date: 09/17/2024 +ms.custom: OPS13 +ms.date: 10/25/2024 PlatyPS schema version: 2024-05-01 title: Compare-CommandHelp --- diff --git a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Export-MamlCommandHelp.md b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Export-MamlCommandHelp.md index e5d4c4ce..d67b480e 100644 --- a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Export-MamlCommandHelp.md +++ b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Export-MamlCommandHelp.md @@ -4,8 +4,8 @@ external help file: Microsoft.PowerShell.PlatyPS.dll-Help.xml HelpUri: '' Locale: en-US Module Name: Microsoft.PowerShell.PlatyPS -ms.custom: OPS10 -ms.date: 09/17/2024 +ms.custom: OPS13 +ms.date: 10/25/2024 PlatyPS schema version: 2024-05-01 title: Export-MamlCommandHelp --- diff --git a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Export-MarkdownCommandHelp.md b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Export-MarkdownCommandHelp.md index be65fcec..3354322e 100644 --- a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Export-MarkdownCommandHelp.md +++ b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Export-MarkdownCommandHelp.md @@ -4,8 +4,8 @@ external help file: Microsoft.PowerShell.PlatyPS.dll-Help.xml HelpUri: '' Locale: en-US Module Name: Microsoft.PowerShell.PlatyPS -ms.custom: OPS10 -ms.date: 09/17/2024 +ms.custom: OPS13 +ms.date: 10/25/2024 PlatyPS schema version: 2024-05-01 title: Export-MarkdownCommandHelp --- diff --git a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Export-MarkdownModuleFile.md b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Export-MarkdownModuleFile.md index 6f854af4..cd98c273 100644 --- a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Export-MarkdownModuleFile.md +++ b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Export-MarkdownModuleFile.md @@ -4,8 +4,8 @@ external help file: Microsoft.PowerShell.PlatyPS.dll-Help.xml HelpUri: '' Locale: en-US Module Name: Microsoft.PowerShell.PlatyPS -ms.custom: OPS10 -ms.date: 09/17/2024 +ms.custom: OPS13 +ms.date: 10/25/2024 PlatyPS schema version: 2024-05-01 title: Export-MarkdownModuleFile --- diff --git a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Export-YamlCommandHelp.md b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Export-YamlCommandHelp.md index cc6a8b16..8c2eae73 100644 --- a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Export-YamlCommandHelp.md +++ b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Export-YamlCommandHelp.md @@ -4,8 +4,8 @@ external help file: Microsoft.PowerShell.PlatyPS.dll-Help.xml HelpUri: '' Locale: en-US Module Name: Microsoft.PowerShell.PlatyPS -ms.custom: OPS10 -ms.date: 09/17/2024 +ms.custom: OPS13 +ms.date: 10/25/2024 PlatyPS schema version: 2024-05-01 title: Export-YamlCommandHelp --- diff --git a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Export-YamlModuleFile.md b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Export-YamlModuleFile.md index ac307a5f..8ca585d6 100644 --- a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Export-YamlModuleFile.md +++ b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Export-YamlModuleFile.md @@ -4,8 +4,8 @@ external help file: Microsoft.PowerShell.PlatyPS.dll-Help.xml HelpUri: '' Locale: en-US Module Name: Microsoft.PowerShell.PlatyPS -ms.custom: OPS10 -ms.date: 09/17/2024 +ms.custom: OPS13 +ms.date: 10/25/2024 PlatyPS schema version: 2024-05-01 title: Export-YamlModuleFile --- diff --git a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Import-MamlHelp.md b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Import-MamlHelp.md index bd4c3373..f4b0c993 100644 --- a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Import-MamlHelp.md +++ b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Import-MamlHelp.md @@ -4,8 +4,8 @@ external help file: Microsoft.PowerShell.PlatyPS.dll-Help.xml HelpUri: '' Locale: en-US Module Name: Microsoft.PowerShell.PlatyPS -ms.custom: OPS10 -ms.date: 09/17/2024 +ms.custom: OPS13 +ms.date: 10/25/2024 PlatyPS schema version: 2024-05-01 title: Import-MamlHelp --- @@ -83,7 +83,7 @@ The path to the MAML help file. Specifies a path to one or more locations. ```yaml Type: System.String[] DefaultValue: '' -SupportsWildcards: false +SupportsWildcards: true ParameterValue: [] Aliases: [] ParameterSets: diff --git a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Import-MarkdownCommandHelp.md b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Import-MarkdownCommandHelp.md index aaf2a5c5..4d33b5f7 100644 --- a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Import-MarkdownCommandHelp.md +++ b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Import-MarkdownCommandHelp.md @@ -4,8 +4,8 @@ external help file: Microsoft.PowerShell.PlatyPS.dll-Help.xml HelpUri: '' Locale: en-US Module Name: Microsoft.PowerShell.PlatyPS -ms.custom: OPS10 -ms.date: 09/17/2024 +ms.custom: OPS13 +ms.date: 10/25/2024 PlatyPS schema version: 2024-05-01 title: Import-MarkdownCommandHelp --- @@ -117,7 +117,7 @@ items in the current location. ```yaml Type: System.String[] DefaultValue: '' -SupportsWildcards: false +SupportsWildcards: true ParameterValue: [] Aliases: [] ParameterSets: diff --git a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Import-MarkdownModuleFile.md b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Import-MarkdownModuleFile.md index 9849f19d..42834ec9 100644 --- a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Import-MarkdownModuleFile.md +++ b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Import-MarkdownModuleFile.md @@ -4,8 +4,8 @@ external help file: Microsoft.PowerShell.PlatyPS.dll-Help.xml HelpUri: '' Locale: en-US Module Name: Microsoft.PowerShell.PlatyPS -ms.custom: OPS10 -ms.date: 09/17/2024 +ms.custom: OPS13 +ms.date: 10/25/2024 PlatyPS schema version: 2024-05-01 title: Import-MarkdownModuleFile --- @@ -99,7 +99,7 @@ items in the current location. ```yaml Type: System.String[] DefaultValue: '' -SupportsWildcards: false +SupportsWildcards: true ParameterValue: [] Aliases: [] ParameterSets: diff --git a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Import-YamlCommandHelp.md b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Import-YamlCommandHelp.md index c32d30fa..14763183 100644 --- a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Import-YamlCommandHelp.md +++ b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Import-YamlCommandHelp.md @@ -4,8 +4,8 @@ external help file: Microsoft.PowerShell.PlatyPS.dll-Help.xml HelpUri: '' Locale: en-US Module Name: Microsoft.PowerShell.PlatyPS -ms.custom: OPS10 -ms.date: 09/17/2024 +ms.custom: OPS13 +ms.date: 10/25/2024 PlatyPS schema version: 2024-05-01 title: Import-YamlCommandHelp --- @@ -133,7 +133,7 @@ The path to the Yaml command file. Specifies a path to one or more locations. ```yaml Type: System.String[] DefaultValue: '' -SupportsWildcards: false +SupportsWildcards: true ParameterValue: [] Aliases: - FullName diff --git a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Import-YamlModuleFile.md b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Import-YamlModuleFile.md index 71caf997..d8d7adfb 100644 --- a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Import-YamlModuleFile.md +++ b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Import-YamlModuleFile.md @@ -4,8 +4,8 @@ external help file: Microsoft.PowerShell.PlatyPS.dll-Help.xml HelpUri: '' Locale: en-US Module Name: Microsoft.PowerShell.PlatyPS -ms.custom: OPS10 -ms.date: 09/17/2024 +ms.custom: OPS13 +ms.date: 10/25/2024 PlatyPS schema version: 2024-05-01 title: Import-YamlModuleFile --- diff --git a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Measure-PlatyPSMarkdown.md b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Measure-PlatyPSMarkdown.md index 728d5de8..fa1a8f73 100644 --- a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Measure-PlatyPSMarkdown.md +++ b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Measure-PlatyPSMarkdown.md @@ -4,8 +4,8 @@ external help file: Microsoft.PowerShell.PlatyPS.dll-Help.xml HelpUri: '' Locale: en-US Module Name: Microsoft.PowerShell.PlatyPS -ms.custom: OPS10 -ms.date: 09/17/2024 +ms.custom: OPS13 +ms.date: 10/25/2024 PlatyPS schema version: 2024-05-01 title: Measure-PlatyPSMarkdown --- diff --git a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Microsoft.PowerShell.PlatyPS.md b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Microsoft.PowerShell.PlatyPS.md index 1a79188e..13fd61f6 100644 --- a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Microsoft.PowerShell.PlatyPS.md +++ b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Microsoft.PowerShell.PlatyPS.md @@ -1,11 +1,12 @@ --- document type: module -HelpInfoUri: '' +Help Version: 1.0.0.0 +HelpInfoUri: https://somehost/somepath/ Locale: en-US Module Guid: 0bdcabef-a4b7-4a6d-bf7e-d879817ebbff Module Name: Microsoft.PowerShell.PlatyPS -ms.custom: OPS10 -ms.date: 09/18/2024 +ms.custom: OPS13 +ms.date: 10/26/2024 PlatyPS schema version: 2024-05-01 title: Microsoft.PowerShell.PlatyPS Module --- @@ -70,6 +71,10 @@ Determines the type of Markdown file. Creates **CommandHelp** objects for a PowerShell command that's loaded in the session. +### [New-HelpCabinetFile](New-HelpCabinetFile.md) + +Creates a help cabinet file for a module that can be published as updateable help content. + ### [New-MarkdownCommandHelp](New-MarkdownCommandHelp.md) Creates Markdown help files for PowerShell modules and commands. @@ -78,6 +83,10 @@ Creates Markdown help files for PowerShell modules and commands. Creates the Markdown module file for a PowerShell module. +### [Show-HelpPreview](Show-HelpPreview.md) + +View MAML file contents as it would appear when output by `Get-Help`. + ### [Test-MarkdownCommandHelp](Test-MarkdownCommandHelp.md) Tests the structure of a Markdown help file. diff --git a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/New-CommandHelp.md b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/New-CommandHelp.md index 5adea77b..1167b4a7 100644 --- a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/New-CommandHelp.md +++ b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/New-CommandHelp.md @@ -4,8 +4,8 @@ external help file: Microsoft.PowerShell.PlatyPS.dll-Help.xml HelpUri: '' Locale: en-US Module Name: Microsoft.PowerShell.PlatyPS -ms.custom: OPS10 -ms.date: 09/17/2024 +ms.custom: OPS13 +ms.date: 10/25/2024 PlatyPS schema version: 2024-05-01 title: New-CommandHelp --- diff --git a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/New-HelpCabinetFile.md b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/New-HelpCabinetFile.md new file mode 100644 index 00000000..87c3a717 --- /dev/null +++ b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/New-HelpCabinetFile.md @@ -0,0 +1,188 @@ +--- +document type: cmdlet +external help file: Microsoft.PowerShell.PlatyPS-Help.xml +HelpUri: '' +Locale: en-US +Module Name: Microsoft.PowerShell.PlatyPS +ms.custom: OPS13 +ms.date: 10/25/2024 +PlatyPS schema version: 2024-05-01 +title: New-HelpCabinetFile +--- + +# New-HelpCabinetFile + +## SYNOPSIS + +Creates a help cabinet file for a module that can be published as updateable help content. + +## SYNTAX + +### __AllParameterSets + +``` +New-HelpCabinetFile [-CabinetFilesFolder] [-MarkdownModuleFile] + [-OutputFolder] [-WhatIf] [-Confirm] [] +``` + +## ALIASES + +## DESCRIPTION + +This cmdlet create `.cab` and `.zip` files that contain help files for a module. + +> [!NOTE] +> This cmdlet depends on the `MakeCab.exe` native command, which is only available on Windows. This +> cmdlet raises an error if used on non-Windows machines. + +This cmdlet uses metadata stored in the module Markdown file to name your `.cab` and `.zip` files. +This naming matches the pattern that the PowerShell help system requires for use as updatable help. + +This cmdlet also generates or updates an existing `Helpinfo.xml` file. That file provides versioning +and locale details to the PowerShell help system. + +## EXAMPLES + +### Example 1 - Create updateable help files for a module + +```powershell +$params = @{ + CabinetFilesFolder = '.\maml\Microsoft.PowerShell.PlatyPS' + MarkdownModuleFile = '.\Microsoft.PowerShell.PlatyPS\Microsoft.PowerShell.PlatyPS.md' + OutputFolder = '.\cab' +} +New-HelpCabinetFile @params +``` + +## PARAMETERS + +### -CabinetFilesFolder + +The path to the folder containing the MAML file to be packaged. + +```yaml +Type: System.String +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: [] +ParameterSets: +- Name: (All) + Position: 0 + IsRequired: true + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -Confirm + +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: System.Management.Automation.SwitchParameter +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: +- cf +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -MarkdownModuleFile + +Specifies the full path of the module Markdown file. + +```yaml +Type: System.String +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: [] +ParameterSets: +- Name: (All) + Position: 1 + IsRequired: true + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -OutputFolder + +The location where you want to write the `.cab`, `.zip`, and `HelpInfo.xml` files. + +```yaml +Type: System.String +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: [] +ParameterSets: +- Name: (All) + Position: 2 + IsRequired: true + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -WhatIf + +Shows what would happen if the cmdlet runs. The cmdlet isn't run. + +```yaml +Type: System.Management.Automation.SwitchParameter +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: +- wi +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, +-ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +## OUTPUTS + +### System.IO.FileInfo + +The **FileInfo** objects that represent the files created by this cmdlet. + +## NOTES + +## RELATED LINKS diff --git a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/New-MarkdownCommandHelp.md b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/New-MarkdownCommandHelp.md index 0635d996..9d4e60f7 100644 --- a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/New-MarkdownCommandHelp.md +++ b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/New-MarkdownCommandHelp.md @@ -4,8 +4,8 @@ external help file: Microsoft.PowerShell.PlatyPS.dll-Help.xml HelpUri: '' Locale: en-US Module Name: Microsoft.PowerShell.PlatyPS -ms.custom: OPS10 -ms.date: 09/17/2024 +ms.custom: OPS13 +ms.date: 10/25/2024 PlatyPS schema version: 2024-05-01 title: New-MarkdownCommandHelp --- diff --git a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/New-MarkdownModuleFile.md b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/New-MarkdownModuleFile.md index 42b55010..7efaec1e 100644 --- a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/New-MarkdownModuleFile.md +++ b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/New-MarkdownModuleFile.md @@ -4,8 +4,8 @@ external help file: Microsoft.PowerShell.PlatyPS.dll-Help.xml HelpUri: '' Locale: en-US Module Name: Microsoft.PowerShell.PlatyPS -ms.custom: OPS10 -ms.date: 09/17/2024 +ms.custom: OPS13 +ms.date: 10/25/2024 PlatyPS schema version: 2024-05-01 title: New-MarkdownModuleFile --- @@ -190,6 +190,28 @@ AcceptedValues: [] HelpMessage: '' ``` +### -HelpUri + +{{ Fill HelpUri Description }} + +```yaml +Type: System.String +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: [] +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + ### -HelpVersion This parameter allows you to specify the version of the help. The default value is `1.0.0.0`. This diff --git a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Show-HelpPreview.md b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Show-HelpPreview.md new file mode 100644 index 00000000..a98269f1 --- /dev/null +++ b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Show-HelpPreview.md @@ -0,0 +1,172 @@ +--- +document type: cmdlet +external help file: Microsoft.PowerShell.PlatyPS-Help.xml +HelpUri: '' +Locale: en-US +Module Name: Microsoft.PowerShell.PlatyPS +ms.custom: OPS13 +ms.date: 10/25/2024 +PlatyPS schema version: 2024-05-01 +title: Show-HelpPreview +--- + +# Show-HelpPreview + +## SYNOPSIS + +View MAML file contents as it would appear when output by `Get-Help`. + +## SYNTAX + +### Path + +``` +Show-HelpPreview [-Path] [-ConvertNotesToList] [-ConvertDoubleDashLists] + [] +``` + +### LiteralPath + +``` +Show-HelpPreview [-LiteralPath] [-ConvertNotesToList] [-ConvertDoubleDashLists] + [] +``` + +## ALIASES + +## DESCRIPTION + +The `Show-HelpPreview` cmdlet displays your generated external help as `Get-Help` output. Specify +one or more files in Microsoft Assistance Markup Language (MAML) format. + +## EXAMPLES + +### Example 1 - Display the contents of a MAML file + +This example displays the contents of PlatyPS MAML file as it would appear when output by +`Get-Help`. + +```powershell +Show-HelpPreview -Path .\Microsoft.PowerShell.PlatyPS\Microsoft.PowerShell.PlatyPS-Help.xml +``` + +## PARAMETERS + +### -ConvertDoubleDashLists + +Indicates that this cmdlet converts double-hyphen list bullets into single-hyphen bullets. +Double-hyphen lists are common in Windows PowerShell documentation. Markdown accepts single-hyphens +for lists. + +```yaml +Type: System.Management.Automation.SwitchParameter +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: [] +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -ConvertNotesToList + +Indicates that this cmdlet formats multiple paragraph items in the **NOTES** section as single list +items. + +```yaml +Type: System.Management.Automation.SwitchParameter +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: [] +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -LiteralPath + +Specifies one or more paths to MAML help files. Wildcards aren't supported. + +```yaml +Type: System.String[] +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: +- PSPath +- LP +ParameterSets: +- Name: LiteralPath + Position: 1 + IsRequired: true + ValueFromPipeline: true + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -Path + +Specifies one or more paths to MAML help files. Wildcards are supported. + +```yaml +Type: System.String[] +DefaultValue: '' +SupportsWildcards: true +ParameterValue: [] +Aliases: [] +ParameterSets: +- Name: Path + Position: 1 + IsRequired: true + ValueFromPipeline: true + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, +-ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### System.String + +You can pipe path strings to this command. + +## OUTPUTS + +### MamlCommandHelpInfo + +This cmdlet returns a `MamlCommandHelpInfo` objects. This is the same object that is returned by +`Get-Help`. + +## NOTES + +## RELATED LINKS + +- [Get-Help](xref:Microsoft.PowerShell.Core.Get-Help) diff --git a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Test-MarkdownCommandHelp.md b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Test-MarkdownCommandHelp.md index be845215..1e7aa03a 100644 --- a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Test-MarkdownCommandHelp.md +++ b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Test-MarkdownCommandHelp.md @@ -4,8 +4,8 @@ external help file: Microsoft.PowerShell.PlatyPS.dll-Help.xml HelpUri: '' Locale: en-US Module Name: Microsoft.PowerShell.PlatyPS -ms.custom: OPS10 -ms.date: 09/17/2024 +ms.custom: OPS13 +ms.date: 10/25/2024 PlatyPS schema version: 2024-05-01 title: Test-MarkdownCommandHelp --- @@ -18,12 +18,6 @@ Tests the structure of a Markdown help file. ## SYNTAX -### __AllParameterSets - -``` -Test-MarkdownCommandHelp [-FullName] [-DetailView] [] -``` - ### Item ``` diff --git a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Update-CommandHelp.md b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Update-CommandHelp.md index cc1b32c4..09e46c58 100644 --- a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Update-CommandHelp.md +++ b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Update-CommandHelp.md @@ -4,8 +4,8 @@ external help file: Microsoft.PowerShell.PlatyPS.dll-Help.xml HelpUri: '' Locale: en-US Module Name: Microsoft.PowerShell.PlatyPS -ms.custom: OPS10 -ms.date: 09/17/2024 +ms.custom: OPS13 +ms.date: 10/25/2024 PlatyPS schema version: 2024-05-01 title: Update-CommandHelp --- diff --git a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Update-MarkdownCommandHelp.md b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Update-MarkdownCommandHelp.md index 9fcae77e..670c7e85 100644 --- a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Update-MarkdownCommandHelp.md +++ b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Update-MarkdownCommandHelp.md @@ -4,8 +4,8 @@ external help file: Microsoft.PowerShell.PlatyPS.dll-Help.xml HelpUri: '' Locale: en-US Module Name: Microsoft.PowerShell.PlatyPS -ms.custom: OPS10 -ms.date: 09/17/2024 +ms.custom: OPS13 +ms.date: 10/25/2024 PlatyPS schema version: 2024-05-01 title: Update-MarkdownCommandHelp --- diff --git a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Update-MarkdownModuleFile.md b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Update-MarkdownModuleFile.md index 267fda0d..e5e8a8d2 100644 --- a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Update-MarkdownModuleFile.md +++ b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Update-MarkdownModuleFile.md @@ -4,8 +4,8 @@ external help file: Microsoft.PowerShell.PlatyPS.dll-Help.xml HelpUri: '' Locale: en-US Module Name: Microsoft.PowerShell.PlatyPS -ms.custom: OPS10 -ms.date: 09/17/2024 +ms.custom: OPS13 +ms.date: 10/25/2024 PlatyPS schema version: 2024-05-01 title: Update-MarkdownModuleFile --- @@ -169,6 +169,28 @@ AcceptedValues: [] HelpMessage: '' ``` +### -HelpUri + +{{ Fill HelpUri Description }} + +```yaml +Type: System.String +DefaultValue: '' +SupportsWildcards: false +ParameterValue: [] +Aliases: [] +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + ### -HelpVersion This parameter allows you to specify the version of the help. The default value is `1.0.0.0`. This @@ -270,29 +292,6 @@ AcceptedValues: [] HelpMessage: '' ``` -### -ModuleFile - -A **ModuleFileInfo** object that represents the module to update. This can be imported from the -existing Markdown module file. - -```yaml -Type: Microsoft.PowerShell.PlatyPS.ModuleFileInfo -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: [] -ParameterSets: -- Name: (All) - Position: 0 - IsRequired: true - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - ### -NoBackup By default, the cmdlet creates a backup of the original Markdown file before updating it. Use this @@ -316,29 +315,6 @@ AcceptedValues: [] HelpMessage: '' ``` -### -OutputFolder - -Specifies the location of where the Markdown module file is written. The cmdlet creates a folder for -each module based on the **CommandHelp** object being processed. - -```yaml -Type: System.String -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: [] -ParameterSets: -- Name: (All) - Position: Named - IsRequired: true - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - ### -Path Specifies a path to one or more module markdown files. From 02a706f803f8e15e04df9672c7ac597a6bf056c2 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Mon, 21 Jul 2025 20:37:11 -0500 Subject: [PATCH 26/27] Remove unneeded content from v1 branch (#776) --- .github/ISSUE_TEMPLATE/Bug_Report.yaml | 70 --- .github/ISSUE_TEMPLATE/Feature_Request.yaml | 20 - .github/ISSUE_TEMPLATE/config.yml | 11 - .gitignore | 16 +- .travis.yml | 24 - CODE_OF_CONDUCT.md | 10 - appveyor.yml | 67 --- build.ps1 | 86 ---- CHANGELOG.md => docs/CHANGELOG.md | 0 .../Compare-CommandHelp.md | 134 ------ .../Export-MamlCommandHelp.md | 210 --------- .../Export-MarkdownCommandHelp.md | 279 ------------ .../Export-MarkdownModuleFile.md | 239 ---------- .../Export-YamlCommandHelp.md | 260 ----------- .../Export-YamlModuleFile.md | 237 ---------- .../Import-MamlHelp.md | 124 ------ .../Import-MarkdownCommandHelp.md | 156 ------- .../Import-MarkdownModuleFile.md | 138 ------ .../Import-YamlCommandHelp.md | 177 -------- .../Import-YamlModuleFile.md | 155 ------- .../Measure-PlatyPSMarkdown.md | 153 ------- .../Microsoft.PowerShell.PlatyPS.md | 106 ----- .../New-CommandHelp.md | 124 ------ .../New-HelpCabinetFile.md | 188 -------- .../New-MarkdownCommandHelp.md | 413 ------------------ .../New-MarkdownModuleFile.md | 354 --------------- .../Show-HelpPreview.md | 172 -------- .../Test-MarkdownCommandHelp.md | 171 -------- .../Update-CommandHelp.md | 177 -------- .../Update-MarkdownCommandHelp.md | 218 --------- .../Update-MarkdownModuleFile.md | 382 ---------------- .../CONTRIBUTING.md | 53 --- .../specs/PlatyPS-Design-Notes.md | 147 ------- .../specs/PowerShellCmdlet.schema.json | 215 --------- .../specs/PowershellCmdletV2.schema.json | 257 ----------- .../specs/Schema-Notes.md | 135 ------ .../specs/alias-prototype.md | 41 -- .../specs/platyps_2.0_about_schema.md | 22 - .../specs/platyps_2.0_cmdlets.md | 158 ------- .../specs/platyps_2.0_update.md | 289 ------------ docs/developer/platyPS/CONTRIBUTING.md | 138 ------ .../{developer/platyPS => }/platyPS.schema.md | 0 .../platyPS/Get-HelpPreview.md | 0 .../platyPS/Get-MarkdownMetadata.md | 0 .../platyPS/Merge-MarkdownHelp.md | 0 .../platyPS/New-ExternalHelp.md | 0 .../platyPS/New-ExternalHelpCab.md | 0 .../platyPS/New-MarkdownAboutHelp.md | 0 .../platyPS/New-MarkdownHelp.md | 0 .../platyPS/New-YamlHelp.md | 0 .../platyPS/Update-MarkdownHelp.md | 0 .../platyPS/Update-MarkdownHelpModule.md | 0 .../platyPS/about_platyPS.md | 0 .../presentation/css/impress-demo.css | 0 .../presentation/images/FFFUUU.png | Bin .../presentation/images/azure-maml.png | Bin .../presentation/images/get-help.png | Bin .../presentation/images/markdown-github.png | Bin .../presentation/images/markdown.png | Bin .../images/pscmdlethelpeditor.png | Bin .../presentation/images/psreadline-maml.png | Bin .../platyPS => }/presentation/index.html | 0 .../platyPS => }/presentation/js/impress.js | 0 63 files changed, 8 insertions(+), 6318 deletions(-) delete mode 100644 .github/ISSUE_TEMPLATE/Bug_Report.yaml delete mode 100644 .github/ISSUE_TEMPLATE/Feature_Request.yaml delete mode 100644 .github/ISSUE_TEMPLATE/config.yml delete mode 100644 .travis.yml delete mode 100644 CODE_OF_CONDUCT.md delete mode 100644 appveyor.yml delete mode 100644 build.ps1 rename CHANGELOG.md => docs/CHANGELOG.md (100%) delete mode 100644 docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Compare-CommandHelp.md delete mode 100644 docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Export-MamlCommandHelp.md delete mode 100644 docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Export-MarkdownCommandHelp.md delete mode 100644 docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Export-MarkdownModuleFile.md delete mode 100644 docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Export-YamlCommandHelp.md delete mode 100644 docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Export-YamlModuleFile.md delete mode 100644 docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Import-MamlHelp.md delete mode 100644 docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Import-MarkdownCommandHelp.md delete mode 100644 docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Import-MarkdownModuleFile.md delete mode 100644 docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Import-YamlCommandHelp.md delete mode 100644 docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Import-YamlModuleFile.md delete mode 100644 docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Measure-PlatyPSMarkdown.md delete mode 100644 docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Microsoft.PowerShell.PlatyPS.md delete mode 100644 docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/New-CommandHelp.md delete mode 100644 docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/New-HelpCabinetFile.md delete mode 100644 docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/New-MarkdownCommandHelp.md delete mode 100644 docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/New-MarkdownModuleFile.md delete mode 100644 docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Show-HelpPreview.md delete mode 100644 docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Test-MarkdownCommandHelp.md delete mode 100644 docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Update-CommandHelp.md delete mode 100644 docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Update-MarkdownCommandHelp.md delete mode 100644 docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Update-MarkdownModuleFile.md delete mode 100644 docs/developer/Microsoft.PowerShell.PlatyPS/CONTRIBUTING.md delete mode 100644 docs/developer/Microsoft.PowerShell.PlatyPS/specs/PlatyPS-Design-Notes.md delete mode 100644 docs/developer/Microsoft.PowerShell.PlatyPS/specs/PowerShellCmdlet.schema.json delete mode 100644 docs/developer/Microsoft.PowerShell.PlatyPS/specs/PowershellCmdletV2.schema.json delete mode 100644 docs/developer/Microsoft.PowerShell.PlatyPS/specs/Schema-Notes.md delete mode 100644 docs/developer/Microsoft.PowerShell.PlatyPS/specs/alias-prototype.md delete mode 100644 docs/developer/Microsoft.PowerShell.PlatyPS/specs/platyps_2.0_about_schema.md delete mode 100644 docs/developer/Microsoft.PowerShell.PlatyPS/specs/platyps_2.0_cmdlets.md delete mode 100644 docs/developer/Microsoft.PowerShell.PlatyPS/specs/platyps_2.0_update.md delete mode 100644 docs/developer/platyPS/CONTRIBUTING.md rename docs/{developer/platyPS => }/platyPS.schema.md (100%) rename docs/{cmdlet-reference => }/platyPS/Get-HelpPreview.md (100%) rename docs/{cmdlet-reference => }/platyPS/Get-MarkdownMetadata.md (100%) rename docs/{cmdlet-reference => }/platyPS/Merge-MarkdownHelp.md (100%) rename docs/{cmdlet-reference => }/platyPS/New-ExternalHelp.md (100%) rename docs/{cmdlet-reference => }/platyPS/New-ExternalHelpCab.md (100%) rename docs/{cmdlet-reference => }/platyPS/New-MarkdownAboutHelp.md (100%) rename docs/{cmdlet-reference => }/platyPS/New-MarkdownHelp.md (100%) rename docs/{cmdlet-reference => }/platyPS/New-YamlHelp.md (100%) rename docs/{cmdlet-reference => }/platyPS/Update-MarkdownHelp.md (100%) rename docs/{cmdlet-reference => }/platyPS/Update-MarkdownHelpModule.md (100%) rename docs/{cmdlet-reference => }/platyPS/about_platyPS.md (100%) rename docs/{developer/platyPS => }/presentation/css/impress-demo.css (100%) rename docs/{developer/platyPS => }/presentation/images/FFFUUU.png (100%) rename docs/{developer/platyPS => }/presentation/images/azure-maml.png (100%) rename docs/{developer/platyPS => }/presentation/images/get-help.png (100%) rename docs/{developer/platyPS => }/presentation/images/markdown-github.png (100%) rename docs/{developer/platyPS => }/presentation/images/markdown.png (100%) rename docs/{developer/platyPS => }/presentation/images/pscmdlethelpeditor.png (100%) rename docs/{developer/platyPS => }/presentation/images/psreadline-maml.png (100%) rename docs/{developer/platyPS => }/presentation/index.html (100%) rename docs/{developer/platyPS => }/presentation/js/impress.js (100%) diff --git a/.github/ISSUE_TEMPLATE/Bug_Report.yaml b/.github/ISSUE_TEMPLATE/Bug_Report.yaml deleted file mode 100644 index 79db15b4..00000000 --- a/.github/ISSUE_TEMPLATE/Bug_Report.yaml +++ /dev/null @@ -1,70 +0,0 @@ -name: Bug report 🐛 -description: Report errors or unexpected behavior 🤔 -labels: Needs-Triage -body: -- type: markdown - attributes: - value: > - This repository is **ONLY** for PlatyPS issues. -- type: checkboxes - attributes: - label: Prerequisites - options: - - label: Write a descriptive title. - required: true - - label: Make sure you are able to repro it on the [latest released version](https://github.com/PowerShell/platyPS/releases) - required: true - - label: Search the existing issues. - required: true -- type: textarea - attributes: - label: Steps to reproduce - description: > - List of steps, sample code, failing test or link to a project that reproduces the behavior. - Make sure you place a stack trace inside a code (```) block to avoid linking unrelated issues. - placeholder: > - I am experiencing a problem with X. - I think Y should be happening but Z is actually happening. - validations: - required: true -- type: textarea - attributes: - label: Expected behavior - render: console - placeholder: | - PS> 2 + 2 - 4 - validations: - required: true -- type: textarea - attributes: - label: Actual behavior - render: console - placeholder: | - PS> 2 + 2 - 5 - validations: - required: true -- type: textarea - attributes: - label: Error details - description: Paste verbatim output from `Get-Error` if PowerShell returns an error. - render: console - placeholder: PS> Get-Error -- type: textarea - attributes: - label: Environment data - description: Paste verbatim output from `Get-Modules` and `$PSVersionTable` below. - render: powershell - placeholder: | - PS> Get-Module PlatyPS -ListAvailable - PS> $PSVersionTable - validations: - required: true -- type: textarea - attributes: - label: Visuals - description: > - Please upload images or animations that can be used to reproduce issues in the area below. - Try the [Steps Recorder](https://support.microsoft.com/en-us/windows/record-steps-to-reproduce-a-problem-46582a9b-620f-2e36-00c9-04e25d784e47) - on Windows or [Screenshot](https://support.apple.com/en-us/HT208721) on macOS. diff --git a/.github/ISSUE_TEMPLATE/Feature_Request.yaml b/.github/ISSUE_TEMPLATE/Feature_Request.yaml deleted file mode 100644 index c8e4cec3..00000000 --- a/.github/ISSUE_TEMPLATE/Feature_Request.yaml +++ /dev/null @@ -1,20 +0,0 @@ -name: Feature Request / Idea 🚀 -description: Suggest a new feature or improvement (this does not mean you have to implement it) -labels: [Issue-Enhancement, Needs-Triage] -body: -- type: textarea - attributes: - label: Summary of the new feature / enhancement - description: > - A clear and concise description of what the problem is that the - new feature would solve. Try formulating it in user story style - (if applicable). - placeholder: "'As a user I want X so that Y...' with X being the being the action and Y being the value of the action." - validations: - required: true -- type: textarea - attributes: - label: Proposed technical implementation details (optional) - placeholder: > - A clear and concise description of what you want to happen. - Consider providing an example PowerShell experience with expected result. diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml deleted file mode 100644 index 089e6e40..00000000 --- a/.github/ISSUE_TEMPLATE/config.yml +++ /dev/null @@ -1,11 +0,0 @@ -blank_issues_enabled: false -contact_links: - - name: Windows PowerShell - url: https://support.microsoft.com/windows/send-feedback-to-microsoft-with-the-feedback-hub-app-f59187f8-8739-22d6-ba93-f66612949332 - about: Windows PowerShell issues or suggestions. - - name: Support - url: https://github.com/PowerShell/PowerShell/blob/master/.github/SUPPORT.md - about: PowerShell Support Questions/Help - - name: Documentation Issue - url: https://github.com/MicrosoftDocs/PowerShell-Docs-Modules/issues/new/choose - about: Please open issues on documentation for PlatyPS here. diff --git a/.gitignore b/.gitignore index 1de269d1..74aeb8ea 100644 --- a/.gitignore +++ b/.gitignore @@ -9,14 +9,14 @@ *.sln.docstates # Build results -[Dd]ebug/ -[Dd]ebugPublic/ -[Rr]elease/ -x64/ -build/ -bld/ -[Bb]in/ -[Oo]bj/ +**/[Dd]ebug/ +**[Dd]ebugPublic/ +**[Rr]elease/ +**x64/ +**build/ +**bld/ +**[Bb]in/ +**[Oo]bj/ # Roslyn cache directories *.ide/ diff --git a/.travis.yml b/.travis.yml deleted file mode 100644 index c260d807..00000000 --- a/.travis.yml +++ /dev/null @@ -1,24 +0,0 @@ -# that gives us dotnet cli installed on the box -language: csharp - -dist: trusty -sudo: required - -mono: none -dotnet: 2.0.0 - -# instruction from https://github.com/PowerShell/PowerShell/blob/master/docs/installation/linux.md#ubuntu-1404 - -install: - - curl https://packages.microsoft.com/keys/microsoft.asc | sudo apt-key add - - - curl https://packages.microsoft.com/config/ubuntu/14.04/prod.list | sudo tee /etc/apt/sources.list.d/microsoft.list - - sudo apt-get update - - sudo apt-get install -y powershell=6.0.2-1.ubuntu.14.04 - -script: - - pwsh ./build.ps1 - - dotnet test ./test/Markdown.MAML.Test - - sudo pwsh -C 'Install-Module Pester -Force' - # updated help is needed for tests, run as a Job to avoid Write-Progress output - - sudo pwsh -C '(update-help &) | Wait-Job' - - pwsh -C 'Invoke-Pester -EnableExit' diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md deleted file mode 100644 index 686e5e7a..00000000 --- a/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,10 +0,0 @@ -# Microsoft Open Source Code of Conduct - -This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). - -Resources: - -- [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/) -- [Microsoft Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) -- Contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with questions or concerns -- Employees can reach out at [aka.ms/opensource/moderation-support](https://aka.ms/opensource/moderation-support) diff --git a/appveyor.yml b/appveyor.yml deleted file mode 100644 index 870d373f..00000000 --- a/appveyor.yml +++ /dev/null @@ -1,67 +0,0 @@ -version: 0.11.0.{build} - -branches: - except: - - v2 - -install: - - ps: | - Write-Host "PowerShell Version:" $PSVersionTable.PSVersion.tostring() - Install-PackageProvider -Name NuGet -MinimumVersion 2.8.5.201 -Force - Install-Module -Name Pester -RequiredVersion 4.10.1 -Force - -init: - - git config --global core.autocrlf true - -build_script: - - ps: | - $ErrorActionPreference = 'Stop' - Update-Help Microsoft.PowerShell.Core, Microsoft.PowerShell.Management, Microsoft.PowerShell.Utility -Force # we need up-to-date help content for tests - .\build.ps1 -Configuration Release - -test_script: - - dotnet test .\test\Markdown.MAML.Test - -after_test: - - ps: | - # We run Pester tests in after_test step - # we don't want to use test_script - # appveyor doesn't run after_test, if tests failed. - # - # Pester tests produce artifacts in .\out directory - $pesterTestResultsFile = ".\TestsResults.xml" - $res = Invoke-Pester -OutputFormat NUnitXml -OutputFile $pesterTestResultsFile -PassThru - (New-Object 'System.Net.WebClient').UploadFile("https://ci.appveyor.com/api/testresults/nunit/$($env:APPVEYOR_JOB_ID)", (Resolve-Path $pesterTestResultsFile)) - # Trying to fail the build, if there are problems - $errorString = '' - # All tests should pass - if ($res.FailedCount -gt 0) { - $errorString += "$($res.FailedCount) tests failed.`n" - } - # Documentation itself should be up-to-date - Update-MarkdownHelp -Path ./docs - $diff = git diff - if ($diff) { - $errorString += "Help is not up-to-date, run Update-MarkdownHelp: $diff`n" - } - if ($errorString) { - throw $errorString - } - -on_finish: - - ps: | - $ErrorActionPreference = 'Stop' - try { - $stagingDirectory = (Resolve-Path ..).Path - $zipFile = Join-Path $stagingDirectory "platyPS-$($env:APPVEYOR_BUILD_VERSION).zip" - Add-Type -assemblyname System.IO.Compression.FileSystem - 7z a -tzip $zipFile "$pwd\out\platyPS" - @( - # You can add other artifacts here - (ls $zipFile), - (ls .\out -File) - # flattering - ) | % {$_} | ? {$_} |% { Push-AppveyorArtifact $_.FullName } - } catch { - Write-Host -Foreground Red $_ - } diff --git a/build.ps1 b/build.ps1 deleted file mode 100644 index e9de3bca..00000000 --- a/build.ps1 +++ /dev/null @@ -1,86 +0,0 @@ -<# -.SYNOPSIS - Builds the MarkDown/MAML DLL and assembles the final package in out\platyPS. -#> -[CmdletBinding()] -param( - [ValidateSet('Debug', 'Release')] - $Configuration = "Debug", - [switch]$SkipDocs, - [string]$DotnetCli -) - -function Find-DotnetCli() -{ - [string] $DotnetCli = '' - $dotnetCmd = Get-Command dotnet - return $dotnetCmd.Path -} - - -if (-not $DotnetCli) { - $DotnetCli = Find-DotnetCli -} - -if (-not $DotnetCli) { - throw "dotnet cli is not found in PATH, install it from https://docs.microsoft.com/en-us/dotnet/core/tools" -} else { - Write-Host "Using dotnet from $DotnetCli" -} - -if (Get-Variable -Name IsCoreClr -ValueOnly -ErrorAction SilentlyContinue) { - $framework = 'netstandard1.6' -} else { - $framework = 'net451' -} - -& $DotnetCli publish ./src/Markdown.MAML -f $framework --output=$pwd/publish /p:Configuration=$Configuration - -$assemblyPaths = ( - (Resolve-Path "publish/Markdown.MAML.dll").Path, - (Resolve-Path "publish/YamlDotNet.dll").Path -) - -# copy artifacts -New-Item -Type Directory out -ErrorAction SilentlyContinue > $null -Copy-Item -Rec -Force src\platyPS out -foreach($assemblyPath in $assemblyPaths) -{ - $assemblyFileName = [System.IO.Path]::GetFileName($assemblyPath) - $outputPath = "out\platyPS\$assemblyFileName" - if ((-not (Test-Path $outputPath)) -or - (Test-Path $outputPath -OlderThan (Get-ChildItem $assemblyPath).LastWriteTime)) - { - Copy-Item $assemblyPath out\platyPS - } else { - Write-Host -Foreground Yellow "Skip $assemblyFileName copying" - } -} - -# copy schema file and docs -Copy-Item .\platyPS.schema.md out\platyPS -New-Item -Type Directory out\platyPS\docs -ErrorAction SilentlyContinue > $null -Copy-Item .\docs\* out\platyPS\docs\ - -# copy template files -New-Item -Type Directory out\platyPS\templates -ErrorAction SilentlyContinue > $null -Copy-Item .\templates\* out\platyPS\templates\ - -# put the right module version -if ($env:APPVEYOR_REPO_TAG_NAME) -{ - $manifest = cat -raw out\platyPS\platyPS.psd1 - $manifest = $manifest -replace "ModuleVersion = '0.0.1'", "ModuleVersion = '$($env:APPVEYOR_REPO_TAG_NAME)'" - Set-Content -Value $manifest -Path out\platyPS\platyPS.psd1 -Encoding Ascii -} - -# dogfooding: generate help for the module -Remove-Module platyPS -ErrorAction SilentlyContinue -Import-Module $pwd\out\platyPS - -if (-not $SkipDocs) { - New-ExternalHelp docs -OutputPath out\platyPS\en-US -Force - # reload module, to apply generated help - Import-Module $pwd\out\platyPS -Force -} - diff --git a/CHANGELOG.md b/docs/CHANGELOG.md similarity index 100% rename from CHANGELOG.md rename to docs/CHANGELOG.md diff --git a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Compare-CommandHelp.md b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Compare-CommandHelp.md deleted file mode 100644 index 5ce78eac..00000000 --- a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Compare-CommandHelp.md +++ /dev/null @@ -1,134 +0,0 @@ ---- -document type: cmdlet -external help file: Microsoft.PowerShell.PlatyPS.dll-Help.xml -HelpUri: '' -Locale: en-US -Module Name: Microsoft.PowerShell.PlatyPS -ms.custom: OPS13 -ms.date: 10/25/2024 -PlatyPS schema version: 2024-05-01 -title: Compare-CommandHelp ---- - -# Compare-CommandHelp - -## SYNOPSIS - -Compares two **CommandHelp** objects and produces a detailed report showing the differences. - -## SYNTAX - -### __AllParameterSets - -``` -Compare-CommandHelp [-ReferenceCommandHelp] [-DifferenceCommandHelp] - [-PropertyNamesToExclude ] [] -``` - -## ALIASES - -## DESCRIPTION - -`Compare-CommandHelp` is a troubleshooting tool that compares two CommandHelp objects and produces a -detailed report showing the differences. For example, you can use this to compare objects imported -from different sources, such as two different versions of Markdown files. - -## EXAMPLES - -### Example 1 - -```powershell -$refcmd = Import-MarkdownCommandHelp -Path .\v1\Microsoft.PowerShell.PlatyPS\Compare-CommandHelp.md -$diffcmd = Import-MarkdownCommandHelp -Path .\v2\Microsoft.PowerShell.PlatyPS\Compare-CommandHelp.md -Compare-CommandHelp -ReferenceCommandHelp $refcmd -DifferenceCommandHelp $diffcmd > .\diff.log -``` - -## PARAMETERS - -### -DifferenceCommandHelp - -The CommandHelp object to compare against the reference object. - -```yaml -Type: Microsoft.PowerShell.PlatyPS.Model.CommandHelp -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: [] -ParameterSets: -- Name: (All) - Position: 1 - IsRequired: true - ValueFromPipeline: false - ValueFromPipelineByPropertyName: true - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### -PropertyNamesToExclude - -A list of one or more property names to exclude from the comparison. - -```yaml -Type: System.String[] -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: [] -ParameterSets: -- Name: (All) - Position: Named - IsRequired: false - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### -ReferenceCommandHelp - -The base CommandHelp object to be compared to the difference object. - -```yaml -Type: Microsoft.PowerShell.PlatyPS.Model.CommandHelp -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: [] -ParameterSets: -- Name: (All) - Position: 0 - IsRequired: true - ValueFromPipeline: false - ValueFromPipelineByPropertyName: true - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### CommonParameters - -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, --InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, --ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see -[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). - -## INPUTS - -### Microsoft.PowerShell.PlatyPS.Model.CommandHelp - -## OUTPUTS - -### System.String - -## NOTES - -## RELATED LINKS - -- [Import-MarkdownHelp](Import-MarkdownHelp.md) -- [Import-YamlCommandHelp](Import-YamlCommandHelp.md) diff --git a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Export-MamlCommandHelp.md b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Export-MamlCommandHelp.md deleted file mode 100644 index d67b480e..00000000 --- a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Export-MamlCommandHelp.md +++ /dev/null @@ -1,210 +0,0 @@ ---- -document type: cmdlet -external help file: Microsoft.PowerShell.PlatyPS.dll-Help.xml -HelpUri: '' -Locale: en-US -Module Name: Microsoft.PowerShell.PlatyPS -ms.custom: OPS13 -ms.date: 10/25/2024 -PlatyPS schema version: 2024-05-01 -title: Export-MamlCommandHelp ---- - -# Export-MamlCommandHelp - -## SYNOPSIS - -Exports **CommandHelp** objects to a MAML file. - -## SYNTAX - -### __AllParameterSets - -``` -Export-MamlCommandHelp [-CommandHelp] [-OutputFolder] - [-Encoding ] [-Force] [-WhatIf] [-Confirm] [] -``` - -## ALIASES - -## DESCRIPTION - -This command converts **CommandHelp** objects to a MAML file. The MAML file contains help content in -the format used by the `Get-Help` command. - -## EXAMPLES - -### Example 1 - Create the MAML help file for a module - -```powershell -$mdfiles = Measure-PlatyPSMarkdown -Path .\v2\Microsoft.PowerShell.PlatyPS\*.md -$mdfiles | Where-Object Filetype -match 'CommandHelp' | - Import-MarkdownCommandHelp -Path {$_.FilePath} | - Export-MamlCommandHelp -OutputFolder .\maml -``` - -```Output - Directory: D:\Git\PS-Src\platyPS\v2docs\maml - -Mode LastWriteTime Length Name ----- ------------- ------ ---- --a--- 8/26/2024 3:18 PM 160928 Microsoft.PowerShell.PlatyPS-Help.xml -``` - -## PARAMETERS - -### -CommandHelp - -One or more **CommandHelp** objects to export. - -```yaml -Type: Microsoft.PowerShell.PlatyPS.Model.CommandHelp[] -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: [] -ParameterSets: -- Name: (All) - Position: 0 - IsRequired: true - ValueFromPipeline: true - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### -Confirm - -Prompts you for confirmation before running the cmdlet. - -```yaml -Type: System.Management.Automation.SwitchParameter -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: -- cf -ParameterSets: -- Name: (All) - Position: Named - IsRequired: false - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### -Encoding - -The encoding to use when writing the markdown file. If no value is specified, encoding defaults to -the value of the `$OutputEncoding` preference variable. - -```yaml -Type: System.Text.Encoding -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: [] -ParameterSets: -- Name: (All) - Position: Named - IsRequired: false - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### -Force - -Use the **Force** parameter to overwrite the output file if it already exists. - -```yaml -Type: System.Management.Automation.SwitchParameter -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: [] -ParameterSets: -- Name: (All) - Position: Named - IsRequired: false - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### -OutputFolder - -The folder where the markdown file is saved. If the folder doesn't exist, it's created. - -```yaml -Type: System.String -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: [] -ParameterSets: -- Name: (All) - Position: 1 - IsRequired: true - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### -WhatIf - -Shows what would happen if the cmdlet runs. The cmdlet isn't run. - -```yaml -Type: System.Management.Automation.SwitchParameter -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: -- wi -ParameterSets: -- Name: (All) - Position: Named - IsRequired: false - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### CommonParameters - -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, --InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, --ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see -[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). - -## INPUTS - -### Microsoft.PowerShell.PlatyPS.Model.CommandHelp - -## OUTPUTS - -### System.IO.FileInfo - -## NOTES - -## RELATED LINKS - -- [Import-MarkdownCommandHelp](Import-MarkdownCommandHelp.md) diff --git a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Export-MarkdownCommandHelp.md b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Export-MarkdownCommandHelp.md deleted file mode 100644 index 3354322e..00000000 --- a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Export-MarkdownCommandHelp.md +++ /dev/null @@ -1,279 +0,0 @@ ---- -document type: cmdlet -external help file: Microsoft.PowerShell.PlatyPS.dll-Help.xml -HelpUri: '' -Locale: en-US -Module Name: Microsoft.PowerShell.PlatyPS -ms.custom: OPS13 -ms.date: 10/25/2024 -PlatyPS schema version: 2024-05-01 -title: Export-MarkdownCommandHelp ---- - -# Export-MarkdownCommandHelp - -## SYNOPSIS - -Exports a **CommandHelp** object to a markdown file. - -## SYNTAX - -### __AllParameterSets - -``` -Export-MarkdownCommandHelp [-CommandHelp] [-Encoding ] [-Force] - [-OutputFolder ] [-Metadata ] [-WhatIf] [-Confirm] [] -``` - -## ALIASES - -## DESCRIPTION - -This command exports a **CommandHelp** object to a markdown file. You can add metadata frontmatter -to the markdown file by using the **Metadata** parameter. You can get a **CommandHelp** object by -using the `Export-MarkdownCommandHelp` cmdlet or one of the `Import-*` cmdlets. - -## EXAMPLES - -### Example 1 - Convert old Markdown help content to the new format - -This example imports Markdown help in the old format from the `.\v1` folder and exports it to the -`.\v2` folder in the new format. - -```powershell -$chobj = Import-MarkdownCommandHelp -Path .\v1\Export-YamlModuleFile.md -Export-MarkdownCommandHelp -CommandHelp $chobj -OutputFolder .\v2 -``` - -```Output - Directory: D:\Git\PS-Src\platyPS\v2docs\v2 - -Mode LastWriteTime Length Name ----- ------------- ------ ---- --a--- 5/20/2024 3:33 PM 2892 Export-YamlModuleFile.md -``` - -### Example 2 - Convert a folder of old Markdown help content to the new format - -This example imports Markdown help in the old format from the `.\v1` folder and exports it to the -`.\v1\new` folder in the new format. If necessary, `Export-MarkdownCommandHelp` creates the -destination folders. The new markdown files are written to folder named for the module they belong -to. - -```powershell -$mdfiles = Measure-PlatyPSMarkdown -Path .\v1\Microsoft.PowerShell.PlatyPS\*.md -$mdfiles | Where-Object Filetype -match 'CommandHelp' | - Import-MarkdownCommandHelp -Path {$_.FilePath} | - Export-MarkdownCommandHelp -OutputFolder .\v1\new -``` - -```Output - Directory: D:\Git\PS-Src\platyPS\v2docs\v1\new\Microsoft.PowerShell.PlatyPS - -Mode LastWriteTime Length Name ----- ------------- ------ ---- --a--- 8/26/2024 3:30 PM 3194 Compare-CommandHelp.md --a--- 8/26/2024 3:30 PM 4282 Export-MamlCommandHelp.md --a--- 8/26/2024 3:30 PM 6401 Export-MarkdownCommandHelp.md --a--- 8/26/2024 3:30 PM 4874 Export-MarkdownModuleFile.md --a--- 8/26/2024 3:30 PM 6429 Export-YamlCommandHelp.md --a--- 8/26/2024 3:30 PM 5601 Export-YamlModuleFile.md --a--- 8/26/2024 3:30 PM 2724 Import-MamlHelp.md --a--- 8/26/2024 3:30 PM 3733 Import-MarkdownCommandHelp.md --a--- 8/26/2024 3:30 PM 3870 Import-MarkdownModuleFile.md --a--- 8/26/2024 3:30 PM 3907 Import-YamlCommandHelp.md --a--- 8/26/2024 3:30 PM 3477 Import-YamlModuleFile.md --a--- 8/26/2024 3:30 PM 2088 Measure-PlatyPSMarkdown.md --a--- 8/26/2024 3:30 PM 4748 New-CommandHelp.md --a--- 8/26/2024 3:30 PM 8647 New-MarkdownCommandHelp.md --a--- 8/26/2024 3:30 PM 5086 New-MarkdownModuleFile.md --a--- 8/26/2024 3:30 PM 3080 Test-MarkdownCommandHelp.md --a--- 8/26/2024 3:30 PM 3041 Update-CommandHelp.md --a--- 8/26/2024 3:30 PM 3981 Update-MarkdownCommandHelp.md --a--- 8/26/2024 3:30 PM 5548 Update-MarkdownModuleFile.md -``` - -## PARAMETERS - -### -CommandHelp - -The **CommandHelp** object to export. You can pass the **CommandHelp** object on the pipeline or by -using the **Command** parameter. - -```yaml -Type: Microsoft.PowerShell.PlatyPS.Model.CommandHelp[] -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: [] -ParameterSets: -- Name: (All) - Position: 0 - IsRequired: true - ValueFromPipeline: true - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### -Confirm - -Prompts you for confirmation before running the cmdlet. - -```yaml -Type: System.Management.Automation.SwitchParameter -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: -- cf -ParameterSets: -- Name: (All) - Position: Named - IsRequired: false - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### -Encoding - -The encoding to use when writing the markdown file. If no value is specified, encoding defaults to -the value of the `$OutputEncoding` preference variable. - -```yaml -Type: System.Text.Encoding -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: [] -ParameterSets: -- Name: (All) - Position: Named - IsRequired: false - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### -Force - -Use the **Force** parameter to overwrite the output file if it already exists. - -```yaml -Type: System.Management.Automation.SwitchParameter -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: [] -ParameterSets: -- Name: (All) - Position: Named - IsRequired: false - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### -Metadata - -The metadata to add to the frontmatter of the markdown file. The metadata is a hashtable where the -you specify the key and value pairs to add to the frontmatter. New key names are added to the -existing frontmatter. The values of existing keys are overwritten. - -```yaml -Type: System.Collections.Hashtable -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: [] -ParameterSets: -- Name: (All) - Position: Named - IsRequired: false - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### -OutputFolder - -The folder where the markdown file is saved. If the folder doesn't exist, it's created. - -```yaml -Type: System.String -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: [] -ParameterSets: -- Name: (All) - Position: Named - IsRequired: false - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### -WhatIf - -Shows what would happen if the cmdlet runs. The cmdlet is not run. - -```yaml -Type: System.Management.Automation.SwitchParameter -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: -- wi -ParameterSets: -- Name: (All) - Position: Named - IsRequired: false - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### CommonParameters - -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, --InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, --ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see -[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). - -## INPUTS - -### Microsoft.PowerShell.PlatyPS.Model.CommandHelp - -## OUTPUTS - -### System.IO.FileInfo - -## NOTES - -## RELATED LINKS - -- [Export-YamlCommandHelp](Export-YamlCommandHelp.md) -- [Import-MarkdownCommandHelp](Import-MarkdownCommandHelp.md) -- [Import-YamlCommandHelp](Import-YamlCommandHelp.md) diff --git a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Export-MarkdownModuleFile.md b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Export-MarkdownModuleFile.md deleted file mode 100644 index cd98c273..00000000 --- a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Export-MarkdownModuleFile.md +++ /dev/null @@ -1,239 +0,0 @@ ---- -document type: cmdlet -external help file: Microsoft.PowerShell.PlatyPS.dll-Help.xml -HelpUri: '' -Locale: en-US -Module Name: Microsoft.PowerShell.PlatyPS -ms.custom: OPS13 -ms.date: 10/25/2024 -PlatyPS schema version: 2024-05-01 -title: Export-MarkdownModuleFile ---- - -# Export-MarkdownModuleFile - -## SYNOPSIS - -Exports a **ModuleFileInfo** object to a markdown file. - -## SYNTAX - -### __AllParameterSets - -``` -Export-MarkdownModuleFile [-ModuleFileInfo] [-Encoding ] [-Force] - [-Metadata ] [-OutputFolder ] [-WhatIf] [-Confirm] [] -``` - -## ALIASES - -## DESCRIPTION - -This command exports a **ModuleFileInfo** object to a markdown file. You can add metadata -frontmatter to the markdown file by using the **Metadata** parameter. You can get a -**ModuleFileInfo** object by using the `Import-MarkdownModuleFile` cmdlet. You can import a module -file that's written in the old format and export it to the new format. - -## EXAMPLES - -### Example 1 - Convert an old module file to the new format - -In this example, a **ModuleFileInfo** object by importing a module Markdown file from the `.\v1` -folder. That object is then exported to a Markdown file in the new format using the -`Export-MarkdownModuleFile`. - -```powershell -Import-MarkdownModuleFile -Path .\v1\Microsoft.PowerShell.PlatyPS\Microsoft.PowerShell.PlatyPS.md | - Export-MarkdownModuleFile -OutputFolder .\v1\new\Microsoft.PowerShell.PlatyPS -Force -``` - -```Output - Directory: D:\Git\PS-Src\platyPS\v2docs\v1\new\Microsoft.PowerShell.PlatyPS - -Mode LastWriteTime Length Name ----- ------------- ------ ---- --a--- 8/26/2024 3:38 PM 2716 Microsoft.PowerShell.PlatyPS.md -``` - -## PARAMETERS - -### -Confirm - -Prompts you for confirmation before running the cmdlet. - -```yaml -Type: System.Management.Automation.SwitchParameter -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: -- cf -ParameterSets: -- Name: (All) - Position: Named - IsRequired: false - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### -Encoding - -The encoding to use when writing the markdown file. If no value is specified, encoding defaults to -the value of the `$OutputEncoding` preference variable. - -```yaml -Type: System.Text.Encoding -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: [] -ParameterSets: -- Name: (All) - Position: Named - IsRequired: false - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### -Force - -Use the **Force** parameter to overwrite the output file if it already exists. - -```yaml -Type: System.Management.Automation.SwitchParameter -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: [] -ParameterSets: -- Name: (All) - Position: Named - IsRequired: false - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### -Metadata - -The metadata to add to the frontmatter of the markdown file. The metadata is a hashtable where the -you specify the key and value pairs to add to the frontmatter. New key names are added to the -existing frontmatter. The values of existing keys are overwritten. - -```yaml -Type: System.Collections.Hashtable -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: [] -ParameterSets: -- Name: (All) - Position: Named - IsRequired: false - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### -ModuleFileInfo - -The **ModuleFileInfo** object to export to a markdown file. This object is created by the -`Import-MarkdownModuleFile` cmdlet. - -```yaml -Type: Microsoft.PowerShell.PlatyPS.ModuleFileInfo[] -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: [] -ParameterSets: -- Name: (All) - Position: 0 - IsRequired: true - ValueFromPipeline: true - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### -OutputFolder - -The folder where the markdown file is saved. If the folder doesn't exist, it's created. - -```yaml -Type: System.String -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: [] -ParameterSets: -- Name: (All) - Position: Named - IsRequired: false - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### -WhatIf - -Shows what would happen if the cmdlet runs. The cmdlet isn't run. - -```yaml -Type: System.Management.Automation.SwitchParameter -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: -- wi -ParameterSets: -- Name: (All) - Position: Named - IsRequired: false - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### CommonParameters - -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, --InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, --ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see -[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). - -## INPUTS - -### Microsoft.PowerShell.PlatyPS.ModuleFileInfo - -## OUTPUTS - -### System.IO.FileInfo - -## NOTES - -## RELATED LINKS - -- [Import-MarkdownModuleFile](Import-MarkdownModuleFile.md) diff --git a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Export-YamlCommandHelp.md b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Export-YamlCommandHelp.md deleted file mode 100644 index 8c2eae73..00000000 --- a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Export-YamlCommandHelp.md +++ /dev/null @@ -1,260 +0,0 @@ ---- -document type: cmdlet -external help file: Microsoft.PowerShell.PlatyPS.dll-Help.xml -HelpUri: '' -Locale: en-US -Module Name: Microsoft.PowerShell.PlatyPS -ms.custom: OPS13 -ms.date: 10/25/2024 -PlatyPS schema version: 2024-05-01 -title: Export-YamlCommandHelp ---- - -# Export-YamlCommandHelp - -## SYNOPSIS - -Exports **CommandHelp** objects to YAML files. - -## SYNTAX - -### __AllParameterSets - -``` -Export-YamlCommandHelp [-CommandHelp] [-Encoding ] [-Force] - [-OutputFolder ] [-Metadata ] [-WhatIf] [-Confirm] [] -``` - -## ALIASES - -## DESCRIPTION - -This command exports a **CommandHelp** object to a Yaml file. You can add metadata frontmatter -to the Yaml file by using the **Metadata** parameter. You can get a **CommandHelp** object by -using the `Export-YamlCommandHelp` cmdlet or one of the `Import-*` cmdlets. - -## EXAMPLES - -### Example 1 - Convert Markdown command help content to Yaml format - -This example imports Markdown help in the old format from the `.\v1` folder and exports it to the -`.\v2` folder in the new format. - -```powershell -$mdfiles = Measure-PlatyPSMarkdown -Path .\v2\Microsoft.PowerShell.PlatyPS\*.md -$mdfiles | Where-Object Filetype -match 'CommandHelp' | - Import-MarkdownCommandHelp -Path {$_.FilePath} | - Export-YamlCommandHelp -OutputFolder .\v2\yaml -``` - -```Output - Directory: D:\Git\PS-Src\platyPS\v2docs\v2\yaml - -Mode LastWriteTime Length Name ----- ------------- ------ ---- --a--- 8/26/2024 3:56 PM 3535 Compare-CommandHelp.yml --a--- 8/26/2024 3:56 PM 4776 Export-MamlCommandHelp.yml --a--- 8/26/2024 3:56 PM 8150 Export-MarkdownCommandHelp.yml --a--- 8/26/2024 3:56 PM 4998 Export-MarkdownModuleFile.yml --a--- 8/26/2024 3:56 PM 6357 Export-YamlCommandHelp.yml --a--- 8/26/2024 3:56 PM 5396 Export-YamlModuleFile.yml --a--- 8/26/2024 3:56 PM 3019 Import-MamlHelp.yml --a--- 8/26/2024 3:56 PM 4235 Import-MarkdownCommandHelp.yml --a--- 8/26/2024 3:56 PM 4318 Import-MarkdownModuleFile.yml --a--- 8/26/2024 3:56 PM 4391 Import-YamlCommandHelp.yml --a--- 8/26/2024 3:56 PM 3862 Import-YamlModuleFile.yml --a--- 8/26/2024 3:56 PM 2325 Measure-PlatyPSMarkdown.yml --a--- 8/26/2024 3:56 PM 5190 New-CommandHelp.yml --a--- 8/26/2024 3:56 PM 8335 New-MarkdownCommandHelp.yml --a--- 8/26/2024 3:56 PM 4697 New-MarkdownModuleFile.yml --a--- 8/26/2024 3:56 PM 3468 Test-MarkdownCommandHelp.yml --a--- 8/26/2024 3:56 PM 3172 Update-CommandHelp.yml --a--- 8/26/2024 3:56 PM 3908 Update-MarkdownCommandHelp.yml --a--- 8/26/2024 3:56 PM 5217 Update-MarkdownModuleFile.yml -``` - -## PARAMETERS - -### -CommandHelp - -The **CommandHelp** object to export. You can pass the **CommandHelp** object on the pipeline or by -using the **Command** parameter. - -```yaml -Type: Microsoft.PowerShell.PlatyPS.Model.CommandHelp[] -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: [] -ParameterSets: -- Name: (All) - Position: 0 - IsRequired: true - ValueFromPipeline: true - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### -Confirm - -Prompts you for confirmation before running the cmdlet. - -```yaml -Type: System.Management.Automation.SwitchParameter -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: -- cf -ParameterSets: -- Name: (All) - Position: Named - IsRequired: false - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### -Encoding - -The encoding to use when writing the markdown file. If no value is specified, encoding defaults to -the value of the `$OutputEncoding` preference variable. - -```yaml -Type: System.Text.Encoding -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: [] -ParameterSets: -- Name: (All) - Position: Named - IsRequired: false - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### -Force - -Use the **Force** parameter to overwrite the output file if it already exists. - -```yaml -Type: System.Management.Automation.SwitchParameter -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: [] -ParameterSets: -- Name: (All) - Position: Named - IsRequired: false - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### -Metadata - -The metadata to add to the frontmatter of the markdown file. The metadata is a hashtable where the -you specify the key and value pairs to add to the frontmatter. New key names are added to the -existing frontmatter. The values of existing keys are overwritten. - -```yaml -Type: System.Collections.Hashtable -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: [] -ParameterSets: -- Name: (All) - Position: Named - IsRequired: false - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### -OutputFolder - -The folder where the markdown file is saved. If the folder doesn't exist, it's created. - -```yaml -Type: System.String -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: [] -ParameterSets: -- Name: (All) - Position: Named - IsRequired: false - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### -WhatIf - -Shows what would happen if the cmdlet runs. The cmdlet isn't run. - -```yaml -Type: System.Management.Automation.SwitchParameter -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: -- wi -ParameterSets: -- Name: (All) - Position: Named - IsRequired: false - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### CommonParameters - -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, --InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, --ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see -[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). - -## INPUTS - -### Microsoft.PowerShell.PlatyPS.Model.CommandHelp - -## OUTPUTS - -### System.IO.FileInfo - -## NOTES - -## RELATED LINKS - -- [Export-YamlCommandHelp](Export-YamlCommandHelp.md) -- [Export-MarkdownCommandHelp](Export-MarkdownCommandHelp.md) -- [Import-MarkdownCommandHelp](Import-MarkdownCommandHelp.md) -- [Import-YamlCommandHelp](Import-YamlCommandHelp.md) diff --git a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Export-YamlModuleFile.md b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Export-YamlModuleFile.md deleted file mode 100644 index 8ca585d6..00000000 --- a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Export-YamlModuleFile.md +++ /dev/null @@ -1,237 +0,0 @@ ---- -document type: cmdlet -external help file: Microsoft.PowerShell.PlatyPS.dll-Help.xml -HelpUri: '' -Locale: en-US -Module Name: Microsoft.PowerShell.PlatyPS -ms.custom: OPS13 -ms.date: 10/25/2024 -PlatyPS schema version: 2024-05-01 -title: Export-YamlModuleFile ---- - -# Export-YamlModuleFile - -## SYNOPSIS - -Exports a **ModuleFileInfo** object to a Yaml file. - -## SYNTAX - -### __AllParameterSets - -``` -Export-YamlModuleFile [-ModuleFileInfo] [-Encoding ] [-Force] - [-OutputFolder ] [-Metadata ] [-WhatIf] [-Confirm] [] -``` - -## ALIASES - -## DESCRIPTION - -This command exports a **ModuleFileInfo** object to a markdown file. You can get a -**ModuleFileInfo** object by using the `Import-MarkdownModuleFile` cmdlet. You can import a module -file that's written in the old format and export it to the new format. - -## EXAMPLES - -### Example 1 - Export a ModuleFileInfo object to a markdown file - -In this example, a **ModuleFileInfo** object by importing a module Markdown file. That object is -then exported to a Yaml file using the `Export-YamlModuleFile`. - -```powershell -Import-MarkdownModuleFile -Path .\v2\Microsoft.PowerShell.PlatyPS\Microsoft.PowerShell.PlatyPS.md | - Export-YamlModuleFile -OutputFolder .\v2\yaml -``` - -```Output - Directory: D:\Git\PS-Src\platyPS\v2docs\v2\yaml - -Mode LastWriteTime Length Name ----- ------------- ------ ---- --a--- 8/26/2024 4:00 PM 2594 Microsoft.PowerShell.PlatyPS.yml -``` - -## PARAMETERS - -### -Confirm - -Prompts you for confirmation before running the cmdlet. - -```yaml -Type: System.Management.Automation.SwitchParameter -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: -- cf -ParameterSets: -- Name: (All) - Position: Named - IsRequired: false - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### -Encoding - -The encoding to use when writing the markdown file. If no value is specified, encoding defaults to -the value of the `$OutputEncoding` preference variable. - -```yaml -Type: System.Text.Encoding -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: [] -ParameterSets: -- Name: (All) - Position: Named - IsRequired: false - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### -Force - -Use the **Force** parameter to overwrite the output file if it already exists. - -```yaml -Type: System.Management.Automation.SwitchParameter -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: [] -ParameterSets: -- Name: (All) - Position: Named - IsRequired: false - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### -Metadata - -The metadata to add to the markdown file. The metadata is a hashtable that contains key-value pairs. - -```yaml -Type: System.Collections.Hashtable -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: [] -ParameterSets: -- Name: (All) - Position: Named - IsRequired: false - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### -ModuleFileInfo - -The **ModuleFileInfo** object to export. You can pass the **ModuleFileInfo** object on the pipeline -or by using the **ModuleFileInfo** parameter. - -```yaml -Type: Microsoft.PowerShell.PlatyPS.ModuleFileInfo[] -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: [] -ParameterSets: -- Name: (All) - Position: 0 - IsRequired: true - ValueFromPipeline: true - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### -OutputFolder - -The **ModuleFileInfo** object to export to a markdown file. This object is created by the -`Import-MarkdownModuleFile` cmdlet. - -```yaml -Type: System.String -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: [] -ParameterSets: -- Name: (All) - Position: Named - IsRequired: false - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### -WhatIf - -Shows what would happen if the cmdlet runs. The cmdlet isn't run. - -```yaml -Type: System.Management.Automation.SwitchParameter -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: -- wi -ParameterSets: -- Name: (All) - Position: Named - IsRequired: false - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### CommonParameters - -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, --InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, --ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see -[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). - -## INPUTS - -### Microsoft.PowerShell.PlatyPS.ModuleFileInfo - -## OUTPUTS - -### System.IO.FileInfo - -## NOTES - -## RELATED LINKS - -- [Export-MarkdownModuleFile](Export-MarkdownModuleFile.md) -- [Import-MarkdownModuleFile](Import-MarkdownModuleFile.md) diff --git a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Import-MamlHelp.md b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Import-MamlHelp.md deleted file mode 100644 index f4b0c993..00000000 --- a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Import-MamlHelp.md +++ /dev/null @@ -1,124 +0,0 @@ ---- -document type: cmdlet -external help file: Microsoft.PowerShell.PlatyPS.dll-Help.xml -HelpUri: '' -Locale: en-US -Module Name: Microsoft.PowerShell.PlatyPS -ms.custom: OPS13 -ms.date: 10/25/2024 -PlatyPS schema version: 2024-05-01 -title: Import-MamlHelp ---- - -# Import-MamlHelp - -## SYNOPSIS - -Imports MAML help from a file and creates **CommandHelp** objects for each command in the file. - -## SYNTAX - -### Path (Default) - -``` -Import-MamlHelp [-Path] [] -``` - -### LiteralPath - -``` -Import-MamlHelp -LiteralPath [] -``` - -## ALIASES - -## DESCRIPTION - -This command can be used to create **CommandHelp** objects from MAML help files. These objects can -be used to generate Markdown help files. You can also use this command to test the validity of the -MAML help files. - -## EXAMPLES - -### Example 1 - -```powershell -Import-MamlHelp -Path .\maml\Microsoft.PowerShell.PlatyPS.dll-Help.xml -``` - -## PARAMETERS - -### -LiteralPath - -The path to the MAML help file. Specifies a path to one or more locations. The value of LiteralPath -is used exactly as it's typed. No characters are interpreted as wildcards. If the path includes -escape characters, enclose it in single quotation marks. Single quotation marks tell PowerShell not -to interpret any characters as escape sequences. - -For more information, see -[about_Quoting_Rules](/powershell/module/microsoft.powershell.core/about/about_quoting_rules). - -```yaml -Type: System.String[] -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: [] -ParameterSets: -- Name: LiteralPath - Position: Named - IsRequired: true - ValueFromPipeline: false - ValueFromPipelineByPropertyName: true - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### -Path - -The path to the MAML help file. Specifies a path to one or more locations. - -```yaml -Type: System.String[] -DefaultValue: '' -SupportsWildcards: true -ParameterValue: [] -Aliases: [] -ParameterSets: -- Name: Path - Position: 0 - IsRequired: true - ValueFromPipeline: true - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### CommonParameters - -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, --InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, --ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see -[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). - -## INPUTS - -### System.String - -## OUTPUTS - -### Microsoft.PowerShell.PlatyPS.Model.CommandHelp - -## NOTES - -The MAML file format doesn't support all the information that can be stored in a **CommandHelp** -object. If you convert the imported information to markdown format, the resulting markdown file -is not a complete representation of the original command. - -## RELATED LINKS - -- [Export-MamlHelp](Export-MamlCommandHelp.md) diff --git a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Import-MarkdownCommandHelp.md b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Import-MarkdownCommandHelp.md deleted file mode 100644 index 4d33b5f7..00000000 --- a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Import-MarkdownCommandHelp.md +++ /dev/null @@ -1,156 +0,0 @@ ---- -document type: cmdlet -external help file: Microsoft.PowerShell.PlatyPS.dll-Help.xml -HelpUri: '' -Locale: en-US -Module Name: Microsoft.PowerShell.PlatyPS -ms.custom: OPS13 -ms.date: 10/25/2024 -PlatyPS schema version: 2024-05-01 -title: Import-MarkdownCommandHelp ---- - -# Import-MarkdownCommandHelp - -## SYNOPSIS - -Imports Markdown help content into **CommandHelp** objects. - -## SYNTAX - -### Path (Default) - -``` -Import-MarkdownCommandHelp [-Path] [] -``` - -### LiteralPath - -``` -Import-MarkdownCommandHelp -LiteralPath [] -``` - -## ALIASES - -## DESCRIPTION - -The command imports Markdown files containing command help and creates **CommandHelp** objects. The -**CommandHelp** object is a structured representation of the help content that can be used to export -to different formats. - -## EXAMPLES - -### Example 1 - Import all cmdlet Markdown files in a folder - -The following example import cmdlet Markdown files in a folder and converts them to **CommandHelp** -objects. These objects can be used to export to different formats. - -```powershell -$mdfiles = Measure-PlatyPSMarkdown -Path .\v2\Microsoft.PowerShell.PlatyPS\*.md -$mdfiles | Where-Object Filetype -match 'CommandHelp' | - Import-MarkdownCommandHelp -Path {$_.FilePath} | - Select-Object Title -``` - -```Output -Title ------ -Compare-CommandHelp -Export-MamlCommandHelp -Export-MarkdownCommandHelp -Export-MarkdownModuleFile -Export-YamlCommandHelp -Export-YamlModuleFile -Import-MamlHelp -Import-MarkdownCommandHelp -Import-MarkdownModuleFile -Import-YamlCommandHelp -Import-YamlModuleFile -Measure-PlatyPSMarkdown -New-CommandHelp -New-MarkdownCommandHelp -New-MarkdownModuleFile -Test-MarkdownCommandHelp -Update-CommandHelp -Update-MarkdownCommandHelp -Update-MarkdownModuleFile -``` - -## PARAMETERS - -### -LiteralPath - -Specifies a path to one or more locations containing markdown files. The value of **LiteralPath** is -used exactly as it's typed. No characters are interpreted as wildcards. If the path includes escape -characters, enclose it in single quotation marks. Single quotation marks tell PowerShell not to -interpret any characters as escape sequences. - -For more information, see -[about_Quoting_Rules](/powershell/module/microsoft.powershell.core/about/about_CommonParameters). - -```yaml -Type: System.String[] -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: [] -ParameterSets: -- Name: LiteralPath - Position: Named - IsRequired: true - ValueFromPipeline: true - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### -Path - -Specifies the path to an item. This cmdlet gets the item at the specified location. Wildcard -characters are permitted. This parameter is required, but the parameter name Path is optional. - -Use a dot (`.`) to specify the current location. Use the wildcard character (`*`) to specify all -items in the current location. - -```yaml -Type: System.String[] -DefaultValue: '' -SupportsWildcards: true -ParameterValue: [] -Aliases: [] -ParameterSets: -- Name: Path - Position: 0 - IsRequired: true - ValueFromPipeline: true - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### CommonParameters - -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, --InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, --ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see -[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). - -## INPUTS - -### System.String - -## OUTPUTS - -### Microsoft.PowerShell.PlatyPS.Model.CommandHelp - -## NOTES - -## RELATED LINKS - -- [Export-MarkdownCommandHelp](Export-MarkdownCommandHelp.md) -- [Export-YamlCommandHelp](Export-YamlCommandHelp.md) -- [Import-YamlCommandHelp](Import-YamlCommandHelp.md) diff --git a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Import-MarkdownModuleFile.md b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Import-MarkdownModuleFile.md deleted file mode 100644 index 42834ec9..00000000 --- a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Import-MarkdownModuleFile.md +++ /dev/null @@ -1,138 +0,0 @@ ---- -document type: cmdlet -external help file: Microsoft.PowerShell.PlatyPS.dll-Help.xml -HelpUri: '' -Locale: en-US -Module Name: Microsoft.PowerShell.PlatyPS -ms.custom: OPS13 -ms.date: 10/25/2024 -PlatyPS schema version: 2024-05-01 -title: Import-MarkdownModuleFile ---- - -# Import-MarkdownModuleFile - -## SYNOPSIS - -Imports a Markdown module file into a **ModuleHelp** object. - -## SYNTAX - -### Path (Default) - -``` -Import-MarkdownModuleFile [-Path] [] -``` - -### LiteralPath - -``` -Import-MarkdownModuleFile -LiteralPath [] -``` - -## ALIASES - -## DESCRIPTION - -The command imports Markdown files containing module help and creates **ModuleHelp** objects. The -**ModuleHelp** object is a structured representation of the help content that can be used to export -to different formats. - -## EXAMPLES - -### Example 1 - Convert - -```powershell -Import-MarkdownModuleFile .\v2\Microsoft.PowerShell.PlatyPS\Microsoft.PowerShell.PlatyPS.md -``` - -```Output -Metadata : {[document type, module], [HelpInfoUri, ], [Locale, en-US], [Module Guid, - 0bdcabef-a4b7-4a6d-bf7e-d879817ebbff]…} -Title : Microsoft.PowerShell.PlatyPS Module -Module : Microsoft.PowerShell.PlatyPS -ModuleGuid : 0bdcabef-a4b7-4a6d-bf7e-d879817ebbff -Description : This module contains cmdlets to help with the creation help content for PowerShell commands. -Locale : en-US -CommandGroups : {Microsoft.PowerShell.PlatyPS.ModuleCommandGroup} -Diagnostics : Microsoft.PowerShell.PlatyPS.Model.Diagnostics -``` - -## PARAMETERS - -### -LiteralPath - -Specifies a path to one or more locations containing markdown files. The value of **LiteralPath** is -used exactly as it's typed. No characters are interpreted as wildcards. If the path includes escape -characters, enclose it in single quotation marks. Single quotation marks tell PowerShell not to -interpret any characters as escape sequences. - -For more information, see -[about_Quoting_Rules](/powershell/module/microsoft.powershell.core/about/about_CommonParameters). - -```yaml -Type: System.String[] -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: [] -ParameterSets: -- Name: LiteralPath - Position: Named - IsRequired: true - ValueFromPipeline: true - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### -Path - -Specifies the path to an item. This cmdlet gets the item at the specified location. Wildcard -characters are permitted. This parameter is required, but the parameter name Path is optional. - -Use a dot (`.`) to specify the current location. Use the wildcard character (`*`) to specify all -items in the current location. - -```yaml -Type: System.String[] -DefaultValue: '' -SupportsWildcards: true -ParameterValue: [] -Aliases: [] -ParameterSets: -- Name: Path - Position: 0 - IsRequired: true - ValueFromPipeline: true - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### CommonParameters - -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, --InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, --ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see -[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). - -## INPUTS - -### System.String - -## OUTPUTS - -### Microsoft.PowerShell.PlatyPS.ModuleFileInfo - -## NOTES - -## RELATED LINKS - -- [Export-MarkdownModuleFile](Export-MarkdownModuleFile.md) -- [Export-YamlModuleFile](Export-YamlModuleFile.md) -- [Import-MarkdownModuleFile](Import-MarkdownModuleFile.md) diff --git a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Import-YamlCommandHelp.md b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Import-YamlCommandHelp.md deleted file mode 100644 index 14763183..00000000 --- a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Import-YamlCommandHelp.md +++ /dev/null @@ -1,177 +0,0 @@ ---- -document type: cmdlet -external help file: Microsoft.PowerShell.PlatyPS.dll-Help.xml -HelpUri: '' -Locale: en-US -Module Name: Microsoft.PowerShell.PlatyPS -ms.custom: OPS13 -ms.date: 10/25/2024 -PlatyPS schema version: 2024-05-01 -title: Import-YamlCommandHelp ---- - -# Import-YamlCommandHelp - -## SYNOPSIS - -Imports Yaml help content into **CommandHelp** objects. - -## SYNTAX - -### Path (Default) - -``` -Import-YamlCommandHelp [-Path] [-AsDictionary] [] -``` - -### LiteralPath - -``` -Import-YamlCommandHelp -LiteralPath [-AsDictionary] [] -``` - -## ALIASES - -## DESCRIPTION - -The command imports Yaml files containing command help and creates **CommandHelp** objects. The -**CommandHelp** object is a structured representation of the help content that can be used to export -to different formats. - -## EXAMPLES - -### Example 1 - Import all cmdlet Yaml files in a folder - -The following example import cmdlet Markdown files in a folder and converts them to **CommandHelp** -objects. These objects can be used to export to different formats. - -```powershell -Import-YamlCommandHelp -Path .\v2\yaml\*-*.yml | Select-Object Title -``` - -```Output -Title ------ -Compare-CommandHelp -Export-MamlCommandHelp -Export-MarkdownCommandHelp -Export-MarkdownModuleFile -Export-YamlCommandHelp -Export-YamlModuleFile -Import-MamlHelp -Import-MarkdownCommandHelp -Import-MarkdownModuleFile -Import-YamlCommandHelp -Import-YamlModuleFile -Measure-PlatyPSMarkdown -New-CommandHelp -New-MarkdownCommandHelp -New-MarkdownModuleFile -Test-MarkdownCommandHelp -Update-CommandHelp -Update-MarkdownCommandHelp -Update-MarkdownModuleFile -``` - -## PARAMETERS - -### -AsDictionary - -By default this cmdlet returns **CommandHelp** objects. When you use this parameter. the cmdlet -returns the same information as an **OrderedDictionary** object. - -```yaml -Type: System.Management.Automation.SwitchParameter -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: [] -ParameterSets: -- Name: (All) - Position: Named - IsRequired: false - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### -LiteralPath - -Specifies a path to one or more Yaml command files. The value of LiteralPath is used exactly as it's -typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose -it in single quotation marks. Single quotation marks tell PowerShell not to interpret any characters -as escape sequences. - -For more information, see -[about_Quoting_Rules](/powershell/module/microsoft.powershell.core/about/about_quoting_rules). - -```yaml -Type: System.String[] -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: [] -ParameterSets: -- Name: LiteralPath - Position: Named - IsRequired: true - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### -Path - -The path to the Yaml command file. Specifies a path to one or more locations. - -```yaml -Type: System.String[] -DefaultValue: '' -SupportsWildcards: true -ParameterValue: [] -Aliases: -- FullName -ParameterSets: -- Name: Path - Position: 0 - IsRequired: true - ValueFromPipeline: true - ValueFromPipelineByPropertyName: true - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### CommonParameters - -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, --InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, --ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see -[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). - -## INPUTS - -### System.String - -## OUTPUTS - -### System.Collections.Specialized.OrderedDictionary - -This cmdlet returns an **OrderedDictionary** object when you use the **AsDictionary** parameter. - -### Microsoft.PowerShell.PlatyPS.Model.CommandHelp - -By default, this cmdlet returns **CommandHelp** objects. - -## NOTES - -## RELATED LINKS - -- [Export-YamlCommandHelp](Export-YamlCommandHelp.md) diff --git a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Import-YamlModuleFile.md b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Import-YamlModuleFile.md deleted file mode 100644 index d8d7adfb..00000000 --- a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Import-YamlModuleFile.md +++ /dev/null @@ -1,155 +0,0 @@ ---- -document type: cmdlet -external help file: Microsoft.PowerShell.PlatyPS.dll-Help.xml -HelpUri: '' -Locale: en-US -Module Name: Microsoft.PowerShell.PlatyPS -ms.custom: OPS13 -ms.date: 10/25/2024 -PlatyPS schema version: 2024-05-01 -title: Import-YamlModuleFile ---- - -# Import-YamlModuleFile - -## SYNOPSIS - -Imports a Yaml module file into a **ModuleHelp** object. - -## SYNTAX - -### Path (Default) - -``` -Import-YamlModuleFile [-Path] [-AsDictionary] [] -``` - -### LiteralPath - -``` -Import-YamlModuleFile -LiteralPath [-AsDictionary] [] -``` - -## ALIASES - -## DESCRIPTION - -The command imports Yaml files containing module help and creates **ModuleHelp** objects. The -**ModuleHelp** object is a structured representation of the help content that can be used to export -to different formats. - -## EXAMPLES - -### Example 1 - Import a Yaml module file to a **ModuleHelp** object - -```powershell -Import-YamlModuleFile .\v2\yaml\Microsoft.PowerShell.PlatyPS.yml -``` - -```Output -Metadata : {[document type, module], [HelpInfoUri, ], [Locale, en-US], [Module Guid, - 0bdcabef-a4b7-4a6d-bf7e-d879817ebbff]…} -Title : Microsoft.PowerShell.PlatyPS Module -Module : Microsoft.PowerShell.PlatyPS -ModuleGuid : 0bdcabef-a4b7-4a6d-bf7e-d879817ebbff -Description : This module contains cmdlets to help with the creation help content for PowerShell commands. -Locale : en-US -CommandGroups : {Microsoft.PowerShell.PlatyPS.ModuleCommandGroup} -Diagnostics : Microsoft.PowerShell.PlatyPS.Model.Diagnostics -``` - -## PARAMETERS - -### -AsDictionary - -By default, the command returns a **ModuleHelp** object. When you use this parameter, the command -returns the **ModuleHelp** data a dictionary object. - -```yaml -Type: System.Management.Automation.SwitchParameter -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: [] -ParameterSets: -- Name: (All) - Position: Named - IsRequired: false - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### -LiteralPath - -Specifies a path to one or more Yaml module files. The value of **LiteralPath** is used exactly as -it's typed. No characters are interpreted as wildcards. If the path includes escape characters, -enclose it in single quotation marks. Single quotation marks tell PowerShell not to interpret any -characters as escape sequences. - -For more information, see -[about_Quoting_Rules](/powershell/module/microsoft.powershell.core/about/about_CommonParameters). - -```yaml -Type: System.String[] -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: [] -ParameterSets: -- Name: LiteralPath - Position: Named - IsRequired: true - ValueFromPipeline: true - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### -Path - -Specifies a path to one or more locations containing Yaml module files. - -```yaml -Type: System.String[] -DefaultValue: '' -SupportsWildcards: true -ParameterValue: [] -Aliases: [] -ParameterSets: -- Name: Path - Position: 0 - IsRequired: true - ValueFromPipeline: true - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### CommonParameters - -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, --InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, --ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see -[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). - -## INPUTS - -### System.String - -## OUTPUTS - -### Microsoft.PowerShell.PlatyPS.ModuleFileInfo - -## NOTES - -## RELATED LINKS - -- [Import-MarkdownModuleFile](Import-MarkdownModuleFile.md) diff --git a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Measure-PlatyPSMarkdown.md b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Measure-PlatyPSMarkdown.md deleted file mode 100644 index fa1a8f73..00000000 --- a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Measure-PlatyPSMarkdown.md +++ /dev/null @@ -1,153 +0,0 @@ ---- -document type: cmdlet -external help file: Microsoft.PowerShell.PlatyPS.dll-Help.xml -HelpUri: '' -Locale: en-US -Module Name: Microsoft.PowerShell.PlatyPS -ms.custom: OPS13 -ms.date: 10/25/2024 -PlatyPS schema version: 2024-05-01 -title: Measure-PlatyPSMarkdown ---- - -# Measure-PlatyPSMarkdown - -## SYNOPSIS - -Determines the type of Markdown file. - -## SYNTAX - -### Path (Default) - -``` -Measure-PlatyPSMarkdown [-Path] [] -``` - -### LiteralPath - -``` -Measure-PlatyPSMarkdown -LiteralPath [] -``` - -## ALIASES - -## DESCRIPTION - -The command reads the content of the file and determines the type of content. The command returns a -**PlatyPSMarkdown** object that contains the content type and schema version of a PlatyPS markdown -file. This is useful for selecting just the files that contain **CommandHelp** or **ModuleHelp** -content. - -## EXAMPLES - -### Example 1 - Measure all Markdown files in a folder - -```powershell -Measure-PlatyPSMarkdown -Path .\v2\Microsoft.PowerShell.PlatyPS\*.md -``` - -```Output -Title Filetype Filepath ------ -------- -------- -Compare-CommandHelp CommandHelp, V2Schema D:\Git\PS-Src\platyPS\v2docs\v2\Microsoft.PowerShell.PlatyPS\Compare-CommandHelp.md -Export-MamlCommandHelp CommandHelp, V2Schema D:\Git\PS-Src\platyPS\v2docs\v2\Microsoft.PowerShell.PlatyPS\Export-MamlCommandHelp.md -Export-MarkdownCommandHelp CommandHelp, V2Schema D:\Git\PS-Src\platyPS\v2docs\v2\Microsoft.PowerShell.PlatyPS\Export-MarkdownCommandHelp.md -Export-MarkdownModuleFile CommandHelp, V2Schema D:\Git\PS-Src\platyPS\v2docs\v2\Microsoft.PowerShell.PlatyPS\Export-MarkdownModuleFile.md -Export-YamlCommandHelp CommandHelp, V2Schema D:\Git\PS-Src\platyPS\v2docs\v2\Microsoft.PowerShell.PlatyPS\Export-YamlCommandHelp.md -Export-YamlModuleFile CommandHelp, V2Schema D:\Git\PS-Src\platyPS\v2docs\v2\Microsoft.PowerShell.PlatyPS\Export-YamlModuleFile.md -Import-MamlHelp CommandHelp, V2Schema D:\Git\PS-Src\platyPS\v2docs\v2\Microsoft.PowerShell.PlatyPS\Import-MamlHelp.md -Import-MarkdownCommandHelp CommandHelp, V2Schema D:\Git\PS-Src\platyPS\v2docs\v2\Microsoft.PowerShell.PlatyPS\Import-MarkdownCommandHelp.md -Import-MarkdownModuleFile CommandHelp, V2Schema D:\Git\PS-Src\platyPS\v2docs\v2\Microsoft.PowerShell.PlatyPS\Import-MarkdownModuleFile.md -Import-YamlCommandHelp CommandHelp, V2Schema D:\Git\PS-Src\platyPS\v2docs\v2\Microsoft.PowerShell.PlatyPS\Import-YamlCommandHelp.md -Import-YamlModuleFile CommandHelp, V2Schema D:\Git\PS-Src\platyPS\v2docs\v2\Microsoft.PowerShell.PlatyPS\Import-YamlModuleFile.md -Measure-PlatyPSMarkdown CommandHelp, V2Schema D:\Git\PS-Src\platyPS\v2docs\v2\Microsoft.PowerShell.PlatyPS\Measure-PlatyPSMarkdown.md -Microsoft.PowerShell.PlatyPS Module ModuleFile, V2Schema D:\Git\PS-Src\platyPS\v2docs\v2\Microsoft.PowerShell.PlatyPS\Microsoft.PowerShell.PlatyPS.md -New-CommandHelp CommandHelp, V2Schema D:\Git\PS-Src\platyPS\v2docs\v2\Microsoft.PowerShell.PlatyPS\New-CommandHelp.md -New-MarkdownCommandHelp CommandHelp, V2Schema D:\Git\PS-Src\platyPS\v2docs\v2\Microsoft.PowerShell.PlatyPS\New-MarkdownCommandHelp.md -New-MarkdownModuleFile CommandHelp, V2Schema D:\Git\PS-Src\platyPS\v2docs\v2\Microsoft.PowerShell.PlatyPS\New-MarkdownModuleFile.md -Test-MarkdownCommandHelp CommandHelp, V2Schema D:\Git\PS-Src\platyPS\v2docs\v2\Microsoft.PowerShell.PlatyPS\Test-MarkdownCommandHelp.md -Update-CommandHelp CommandHelp, V2Schema D:\Git\PS-Src\platyPS\v2docs\v2\Microsoft.PowerShell.PlatyPS\Update-CommandHelp.md -Update-MarkdownCommandHelp CommandHelp, V2Schema D:\Git\PS-Src\platyPS\v2docs\v2\Microsoft.PowerShell.PlatyPS\Update-MarkdownCommandHelp.md -Update-MarkdownModuleFile CommandHelp, V2Schema D:\Git\PS-Src\platyPS\v2docs\v2\Microsoft.PowerShell.PlatyPS\Update-MarkdownModuleFile.md -``` - -## PARAMETERS - -### -LiteralPath - -Specifies a path to one or more Markdown files. The value of **LiteralPath** is used exactly as it's -typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose -it in single quotation marks. Single quotation marks tell PowerShell not to interpret any characters -as escape sequences. - -For more information, see -[about_Quoting_Rules](/powershell/module/microsoft.powershell.core/about/about_quoting_rules). - -```yaml -Type: System.String[] -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: [] -ParameterSets: -- Name: LiteralPath - Position: Named - IsRequired: true - ValueFromPipeline: true - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### -Path - -The path to one or more Markdown files. Specifies a path to one or more locations. - -```yaml -Type: System.String[] -DefaultValue: '' -SupportsWildcards: true -ParameterValue: [] -Aliases: [] -ParameterSets: -- Name: Path - Position: 0 - IsRequired: true - ValueFromPipeline: true - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### CommonParameters - -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, --InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, --ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see -[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). - -## INPUTS - -### System.String - -## OUTPUTS - -### Microsoft.PowerShell.PlatyPS.MarkdownProbeInfo - -## NOTES - -For old format markdown files, the command examines the frontmatter and H2 structure to determine -the content type. For new format markdown files, the command examines the `document type` key in the -frontmatter. - -The command doesn't validate the full structure of the markdown file. Use `Test-MarkdownCommandHelp` -to validate the structure of the markdown file. - -## RELATED LINKS - -- [Test-MarkdownCommandHelp](Test-MarkdownCommandHelp.md) diff --git a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Microsoft.PowerShell.PlatyPS.md b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Microsoft.PowerShell.PlatyPS.md deleted file mode 100644 index 13fd61f6..00000000 --- a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Microsoft.PowerShell.PlatyPS.md +++ /dev/null @@ -1,106 +0,0 @@ ---- -document type: module -Help Version: 1.0.0.0 -HelpInfoUri: https://somehost/somepath/ -Locale: en-US -Module Guid: 0bdcabef-a4b7-4a6d-bf7e-d879817ebbff -Module Name: Microsoft.PowerShell.PlatyPS -ms.custom: OPS13 -ms.date: 10/26/2024 -PlatyPS schema version: 2024-05-01 -title: Microsoft.PowerShell.PlatyPS Module ---- - -# Microsoft.PowerShell.PlatyPS Module - -## Description - -This module contains cmdlets to help with the creation help content for PowerShell commands. - -## Microsoft.PowerShell.PlatyPS Cmdlets - -### [Compare-CommandHelp](Compare-CommandHelp.md) - -Compares two **CommandHelp** objects and produces a detailed report showing the differences. - -### [Export-MamlCommandHelp](Export-MamlCommandHelp.md) - -Exports **CommandHelp** objects to a MAML file. - -### [Export-MarkdownCommandHelp](Export-MarkdownCommandHelp.md) - -Exports a **CommandHelp** object to a markdown file. - -### [Export-MarkdownModuleFile](Export-MarkdownModuleFile.md) - -Exports a **ModuleFileInfo** object to a markdown file. - -### [Export-YamlCommandHelp](Export-YamlCommandHelp.md) - -Exports **CommandHelp** objects to YAML files. - -### [Export-YamlModuleFile](Export-YamlModuleFile.md) - -Exports a **ModuleFileInfo** object to a Yaml file. - -### [Import-MamlHelp](Import-MamlHelp.md) - -Imports MAML help from a file and creates **CommandHelp** objects for each command in the file. - -### [Import-MarkdownCommandHelp](Import-MarkdownCommandHelp.md) - -Imports Markdown help content into **CommandHelp** objects. - -### [Import-MarkdownModuleFile](Import-MarkdownModuleFile.md) - -Imports a Markdown module file into a **ModuleHelp** object. - -### [Import-YamlCommandHelp](Import-YamlCommandHelp.md) - -Imports Yaml help content into **CommandHelp** objects. - -### [Import-YamlModuleFile](Import-YamlModuleFile.md) - -Imports a Yaml module file into a **ModuleHelp** object. - -### [Measure-PlatyPSMarkdown](Measure-PlatyPSMarkdown.md) - -Determines the type of Markdown file. - -### [New-CommandHelp](New-CommandHelp.md) - -Creates **CommandHelp** objects for a PowerShell command that's loaded in the session. - -### [New-HelpCabinetFile](New-HelpCabinetFile.md) - -Creates a help cabinet file for a module that can be published as updateable help content. - -### [New-MarkdownCommandHelp](New-MarkdownCommandHelp.md) - -Creates Markdown help files for PowerShell modules and commands. - -### [New-MarkdownModuleFile](New-MarkdownModuleFile.md) - -Creates the Markdown module file for a PowerShell module. - -### [Show-HelpPreview](Show-HelpPreview.md) - -View MAML file contents as it would appear when output by `Get-Help`. - -### [Test-MarkdownCommandHelp](Test-MarkdownCommandHelp.md) - -Tests the structure of a Markdown help file. - -### [Update-CommandHelp](Update-CommandHelp.md) - -Updates an imported **CommandHelp** object with the information from session cmdlet of the same -name. - -### [Update-MarkdownCommandHelp](Update-MarkdownCommandHelp.md) - -Updates an imported Markdown command file with the information from session cmdlet of the same name. - -### [Update-MarkdownModuleFile](Update-MarkdownModuleFile.md) - -Updates the Markdown module file. - diff --git a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/New-CommandHelp.md b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/New-CommandHelp.md deleted file mode 100644 index 1167b4a7..00000000 --- a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/New-CommandHelp.md +++ /dev/null @@ -1,124 +0,0 @@ ---- -document type: cmdlet -external help file: Microsoft.PowerShell.PlatyPS.dll-Help.xml -HelpUri: '' -Locale: en-US -Module Name: Microsoft.PowerShell.PlatyPS -ms.custom: OPS13 -ms.date: 10/25/2024 -PlatyPS schema version: 2024-05-01 -title: New-CommandHelp ---- - -# New-CommandHelp - -## SYNOPSIS - -Creates **CommandHelp** objects for a PowerShell command that's loaded in the session. - -## SYNTAX - -### __AllParameterSets - -``` -New-CommandHelp [-CommandInfo] [] -``` - -## ALIASES - -## DESCRIPTION - -This cmdlet takes a list of one or more PowerShell commands and creates **CommandHelp** objects for -each command. The **CommandHelp** object is a structured representation of the help content that can -be used to export to different formats. - -## EXAMPLES - -### Example 1 - Creates a **CommandHelp** object for a cmdlet - -The following example creates a **CommandHelp** object for the `New-PSSession` cmdlet. The -`Get-Member` cmdlet is used to display the properties and methods of the **CommandHelp** object. - -```powershell -New-CommandHelp New-PSSession | Get-Member -``` - -```Output - TypeName: Microsoft.PowerShell.PlatyPS.Model.CommandHelp - -Name MemberType Definition ----- ---------- ---------- -Equals Method bool Equals(Microsoft.PowerShell.PlatyPS.Model.CommandHelp other)... -GetHashCode Method int GetHashCode() -GetType Method type GetType() -ToString Method string ToString() -TryGetParameter Method bool TryGetParameter(string name, [ref] Microsoft.PowerShell.Plat... -Aliases Property System.Collections.Generic.List[string] Aliases {get;} -Description Property string Description {get;set;} -Diagnostics Property Microsoft.PowerShell.PlatyPS.Model.Diagnostics Diagnostics {get;s... -Examples Property System.Collections.Generic.List[Microsoft.PowerShell.PlatyPS.Mode... -ExternalHelpFile Property string ExternalHelpFile {get;set;} -HasCmdletBinding Property bool HasCmdletBinding {get;set;} -HasWorkflowCommonParameters Property bool HasWorkflowCommonParameters {get;set;} -Inputs Property System.Collections.Generic.List[Microsoft.PowerShell.PlatyPS.Mode... -Locale Property cultureinfo Locale {get;set;} -Metadata Property ordered Metadata {get;set;} -ModuleGuid Property System.Nullable[guid] ModuleGuid {get;set;} -ModuleName Property string ModuleName {get;set;} -Notes Property string Notes {get;set;} -OnlineVersionUrl Property string OnlineVersionUrl {get;set;} -Outputs Property System.Collections.Generic.List[Microsoft.PowerShell.PlatyPS.Mode... -Parameters Property System.Collections.Generic.List[Microsoft.PowerShell.PlatyPS.Mode... -RelatedLinks Property System.Collections.Generic.List[Microsoft.PowerShell.PlatyPS.Mode... -SchemaVersion Property string SchemaVersion {get;set;} -Synopsis Property string Synopsis {get;set;} -Syntax Property System.Collections.Generic.List[Microsoft.PowerShell.PlatyPS.Mode... -Title Property string Title {get;set;} -``` - -## PARAMETERS - -### -CommandInfo - -A list of one or more PowerShell commands (cmdlets, functions, scripts). The cmdlet creates a -**CommandHelp** object for each command. - -```yaml -Type: System.Management.Automation.CommandInfo[] -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: [] -ParameterSets: -- Name: (All) - Position: 0 - IsRequired: true - ValueFromPipeline: true - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### CommonParameters - -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, --InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, --ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see -[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). - -## INPUTS - -### System.Management.Automation.CommandInfo - -## OUTPUTS - -### Microsoft.PowerShell.PlatyPS.Model.CommandHelp - -## NOTES - -## RELATED LINKS - -- [Export-MarkdownCommandHelp](Export-MarkdownCommandHelp.md) -- [Export-YamlCommandHelp](Export-YamlCommandHelp.md) diff --git a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/New-HelpCabinetFile.md b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/New-HelpCabinetFile.md deleted file mode 100644 index 87c3a717..00000000 --- a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/New-HelpCabinetFile.md +++ /dev/null @@ -1,188 +0,0 @@ ---- -document type: cmdlet -external help file: Microsoft.PowerShell.PlatyPS-Help.xml -HelpUri: '' -Locale: en-US -Module Name: Microsoft.PowerShell.PlatyPS -ms.custom: OPS13 -ms.date: 10/25/2024 -PlatyPS schema version: 2024-05-01 -title: New-HelpCabinetFile ---- - -# New-HelpCabinetFile - -## SYNOPSIS - -Creates a help cabinet file for a module that can be published as updateable help content. - -## SYNTAX - -### __AllParameterSets - -``` -New-HelpCabinetFile [-CabinetFilesFolder] [-MarkdownModuleFile] - [-OutputFolder] [-WhatIf] [-Confirm] [] -``` - -## ALIASES - -## DESCRIPTION - -This cmdlet create `.cab` and `.zip` files that contain help files for a module. - -> [!NOTE] -> This cmdlet depends on the `MakeCab.exe` native command, which is only available on Windows. This -> cmdlet raises an error if used on non-Windows machines. - -This cmdlet uses metadata stored in the module Markdown file to name your `.cab` and `.zip` files. -This naming matches the pattern that the PowerShell help system requires for use as updatable help. - -This cmdlet also generates or updates an existing `Helpinfo.xml` file. That file provides versioning -and locale details to the PowerShell help system. - -## EXAMPLES - -### Example 1 - Create updateable help files for a module - -```powershell -$params = @{ - CabinetFilesFolder = '.\maml\Microsoft.PowerShell.PlatyPS' - MarkdownModuleFile = '.\Microsoft.PowerShell.PlatyPS\Microsoft.PowerShell.PlatyPS.md' - OutputFolder = '.\cab' -} -New-HelpCabinetFile @params -``` - -## PARAMETERS - -### -CabinetFilesFolder - -The path to the folder containing the MAML file to be packaged. - -```yaml -Type: System.String -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: [] -ParameterSets: -- Name: (All) - Position: 0 - IsRequired: true - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### -Confirm - -Prompts you for confirmation before running the cmdlet. - -```yaml -Type: System.Management.Automation.SwitchParameter -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: -- cf -ParameterSets: -- Name: (All) - Position: Named - IsRequired: false - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### -MarkdownModuleFile - -Specifies the full path of the module Markdown file. - -```yaml -Type: System.String -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: [] -ParameterSets: -- Name: (All) - Position: 1 - IsRequired: true - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### -OutputFolder - -The location where you want to write the `.cab`, `.zip`, and `HelpInfo.xml` files. - -```yaml -Type: System.String -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: [] -ParameterSets: -- Name: (All) - Position: 2 - IsRequired: true - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### -WhatIf - -Shows what would happen if the cmdlet runs. The cmdlet isn't run. - -```yaml -Type: System.Management.Automation.SwitchParameter -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: -- wi -ParameterSets: -- Name: (All) - Position: Named - IsRequired: false - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### CommonParameters - -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, --InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, --ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see -[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). - -## INPUTS - -## OUTPUTS - -### System.IO.FileInfo - -The **FileInfo** objects that represent the files created by this cmdlet. - -## NOTES - -## RELATED LINKS diff --git a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/New-MarkdownCommandHelp.md b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/New-MarkdownCommandHelp.md deleted file mode 100644 index 9d4e60f7..00000000 --- a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/New-MarkdownCommandHelp.md +++ /dev/null @@ -1,413 +0,0 @@ ---- -document type: cmdlet -external help file: Microsoft.PowerShell.PlatyPS.dll-Help.xml -HelpUri: '' -Locale: en-US -Module Name: Microsoft.PowerShell.PlatyPS -ms.custom: OPS13 -ms.date: 10/25/2024 -PlatyPS schema version: 2024-05-01 -title: New-MarkdownCommandHelp ---- - -# New-MarkdownCommandHelp - -## SYNOPSIS - -Creates Markdown help files for PowerShell modules and commands. - -## SYNTAX - -### __AllParameterSets - -``` -New-MarkdownCommandHelp -OutputFolder [-CommandInfo ] [-Encoding ] - [-Force] [-HelpUri ] [-HelpInfoUri ] [-HelpVersion ] [-Locale ] - [-Metadata ] [-ModuleInfo ] [-WithModulePage] - [-AbbreviateParameterTypename] [-WhatIf] [-Confirm] [] -``` - -## ALIASES - -## DESCRIPTION - -Creates Markdown help files for PowerShell modules and commands. - -## EXAMPLES - -### Example 1 - Create Markdown help files for a module - -```powershell -$newMarkdownCommandHelpSplat = @{ - ModuleInfo = Get-Module Microsoft.PowerShell.PlatyPS - OutputFolder = '.' - HelpVersion = '1.0.0.0' - WithModulePage = $true -} -New-MarkdownCommandHelp @newMarkdownCommandHelpSplat -``` - -### Example 2 - Create Markdown help files from a list of commands - -```powershell -$newMarkdownCommandHelpSplat = @{ - CommandInfo = Get-Command -Module Microsoft.PowerShell.PlatyPS - OutputFolder = '.' - HelpVersion = '1.0.0.0' - WithModulePage = $true -} -New-MarkdownCommandHelp @newMarkdownCommandHelpSplat -``` - -## PARAMETERS - -### -AbbreviateParameterTypename - -By default, this command uses full type names in the parameter metadata and for the input and output -types. When you use this parameter, the cmdlet outputs short type names. - -```yaml -Type: System.Management.Automation.SwitchParameter -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: [] -ParameterSets: -- Name: (All) - Position: Named - IsRequired: false - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### -CommandInfo - -A list of one or more commands to create help for. - -```yaml -Type: System.Management.Automation.CommandInfo[] -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: [] -ParameterSets: -- Name: (All) - Position: Named - IsRequired: false - ValueFromPipeline: true - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### -Confirm - -Prompts you for confirmation before running the cmdlet. - -```yaml -Type: System.Management.Automation.SwitchParameter -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: -- cf -ParameterSets: -- Name: (All) - Position: Named - IsRequired: false - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### -Encoding - -The encoding used when creating the output files. If not specified, the cmdlet uses value specified -by `$OutputEncoding`. - -```yaml -Type: System.Text.Encoding -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: [] -ParameterSets: -- Name: (All) - Position: Named - IsRequired: false - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### -Force - -By default, this command doesn't overwrite existing files. When you use this parameter, the cmdlet -overwrites existing files. - -```yaml -Type: System.Management.Automation.SwitchParameter -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: [] -ParameterSets: -- Name: (All) - Position: Named - IsRequired: false - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### -HelpInfoUri - -This parameter allows you to specify the URI used for updateable help. By default, the cmdlet uses -the HelpInfoUri specified in the module manifest. - -```yaml -Type: System.String -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: [] -ParameterSets: -- Name: (All) - Position: Named - IsRequired: false - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### -HelpUri - -This parameter allows you to specify the URI used for online help. By default, the cmdlet uses the -URI defined in the `[CmdletBinding()]` attribute for the command. - -```yaml -Type: System.String -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: [] -ParameterSets: -- Name: (All) - Position: Named - IsRequired: false - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### -HelpVersion - -This parameter allows you to specify the version of the help. The default value is `1.0.0.0`. This -version is written to the `HelpInfo.xml` file that is used for updateable help. - -```yaml -Type: System.Version -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: [] -ParameterSets: -- Name: (All) - Position: Named - IsRequired: false - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### -Locale - -This parameter allows you to specify the language locale for the help files. By default, the cmdlet -uses the current **CultureInfo**. Use the `Get-Culture` cmdlet to see the current culture settings -on your system. - -```yaml -Type: System.String -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: [] -ParameterSets: -- Name: (All) - Position: Named - IsRequired: false - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### -Metadata - -The metadata to add to the frontmatter of the markdown file. The metadata is a hashtable where the -you specify the key and value pairs to add to the frontmatter. New key names are added to the -existing frontmatter. The values of existing keys are overwritten. You can't overwrite the values of -the `document type` or `PlatyPS schema version` keys. If these keys are present in the hashtable, -the cmdlet ignores the values and outputs a warning. - -```yaml -Type: System.Collections.Hashtable -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: [] -ParameterSets: -- Name: (All) - Position: Named - IsRequired: false - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### -ModuleInfo - -A list of one or more modules to create help for. The cmdlet creates Markdown help files for all -commands in the module. The cmdlet creates a folder matching the name of the module in the output -location. All Markdown files are written to the module folder. - -```yaml -Type: System.Management.Automation.PSModuleInfo[] -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: [] -ParameterSets: -- Name: (All) - Position: Named - IsRequired: false - ValueFromPipeline: true - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### -OutputFolder - -Specifies the location of where the Markdown help files are written. The cmdlet creates a folder for -each module being processed. If the target command isn't associated with a module, the cmdlet -creates a the Markdown file in the root of the output folder. - -```yaml -Type: System.String -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: [] -ParameterSets: -- Name: (All) - Position: Named - IsRequired: true - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### -WhatIf - -Shows what would happen if the cmdlet runs. The cmdlet isn't run. - -```yaml -Type: System.Management.Automation.SwitchParameter -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: -- wi -ParameterSets: -- Name: (All) - Position: Named - IsRequired: false - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### -WithModulePage - -By default, this cmdlet only creates Markdown files for commands. When you use this parameter, the -cmdlet creates a Markdown file for the module. This Markdown file contains a list of all commands in -the module and metadata used to create the HelpInfo.xml file. - -```yaml -Type: System.Management.Automation.SwitchParameter -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: [] -ParameterSets: -- Name: (All) - Position: Named - IsRequired: false - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### CommonParameters - -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, --InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, --ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see -[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). - -## INPUTS - -### System.Management.Automation.CommandInfo - -### System.Management.Automation.PSModuleInfo - -## OUTPUTS - -### System.IO.FileInfo - -## NOTES - -## RELATED LINKS - -- [Export-MarkdownCommandHelp](Export-MarkdownCommandHelp.md) diff --git a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/New-MarkdownModuleFile.md b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/New-MarkdownModuleFile.md deleted file mode 100644 index 7efaec1e..00000000 --- a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/New-MarkdownModuleFile.md +++ /dev/null @@ -1,354 +0,0 @@ ---- -document type: cmdlet -external help file: Microsoft.PowerShell.PlatyPS.dll-Help.xml -HelpUri: '' -Locale: en-US -Module Name: Microsoft.PowerShell.PlatyPS -ms.custom: OPS13 -ms.date: 10/25/2024 -PlatyPS schema version: 2024-05-01 -title: New-MarkdownModuleFile ---- - -# New-MarkdownModuleFile - -## SYNOPSIS - -Creates the Markdown module file for a PowerShell module. - -## SYNTAX - -### __AllParameterSets - -``` -New-MarkdownModuleFile -OutputFolder [-CommandHelp ] [-Encoding ] - [-Force] [-HelpUri ] [-HelpInfoUri ] [-HelpVersion ] [-Locale ] - [-Metadata ] [-WhatIf] [-Confirm] [] -``` - -## ALIASES - -## DESCRIPTION - -This command creates the Markdown module file for a PowerShell module. The module file contains the -module metadata and a list of all commands with their synopsis descriptions. This file can be used -as the module landing page in a documentation set. The module metadata is used to by -`Export-MamlCommandHelp` to create the MAML help file for the module. - -## EXAMPLES - -### Example 1 - Create a new module file from a folder of command help files - -```powershell -$mdfiles = Measure-PlatyPSMarkdown -Path .\v2\Microsoft.PowerShell.PlatyPS\*.md -$mdfiles | Where-Object Filetype -match 'CommandHelp' | - Import-MarkdownCommandHelp -Path {$_.FilePath} | - New-MarkdownModuleFile -OutputFolder .\v2 -Force -``` - -```Output - Directory: D:\Docs\v2\Microsoft.PowerShell.PlatyPS - -Mode LastWriteTime Length Name ----- ------------- ------ ---- --a--- 9/18/2024 1:49 PM 2129 Microsoft.PowerShell.PlatyPS.md -``` - -### Example 2 - Create a new module file from a list of commands - -```powershell -$newMarkdownCommandHelpSplat = @{ - CommandHelp = Get-Command -Module Microsoft.PowerShell.PlatyPS | New-CommandHelp - OutputFolder = '.\new' - Force = $true -} -New-MarkdownModuleFile @newMarkdownCommandHelpSplat -``` - -```Output - Directory: D:\Docs\new\Microsoft.PowerShell.PlatyPS - -Mode LastWriteTime Length Name ----- ------------- ------ ---- --a--- 9/18/2024 1:49 PM 2129 Microsoft.PowerShell.PlatyPS.md -``` - -## PARAMETERS - -### -CommandHelp - -The **CommandHelp** objects to be included in the module file. You can pass the **CommandHelp** -object on the pipeline or by using the **Command** parameter. - -```yaml -Type: Microsoft.PowerShell.PlatyPS.Model.CommandHelp[] -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: [] -ParameterSets: -- Name: (All) - Position: Named - IsRequired: false - ValueFromPipeline: true - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### -Confirm - -Prompts you for confirmation before running the cmdlet. - -```yaml -Type: System.Management.Automation.SwitchParameter -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: -- cf -ParameterSets: -- Name: (All) - Position: Named - IsRequired: false - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### -Encoding - -The encoding used when creating the output files. If not specified, the cmdlet uses value specified -by `$OutputEncoding`. - -```yaml -Type: System.Text.Encoding -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: [] -ParameterSets: -- Name: (All) - Position: Named - IsRequired: false - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### -Force - -By default, this command doesn't overwrite existing files. When you use this parameter, the cmdlet -overwrites existing files. - -```yaml -Type: System.Management.Automation.SwitchParameter -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: [] -ParameterSets: -- Name: (All) - Position: Named - IsRequired: false - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### -HelpInfoUri - -This parameter allows you to specify the URI used for updateable help. By default, the cmdlet uses -the HelpInfoUri specified in the module manifest. - -```yaml -Type: System.String -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: [] -ParameterSets: -- Name: (All) - Position: Named - IsRequired: false - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### -HelpUri - -{{ Fill HelpUri Description }} - -```yaml -Type: System.String -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: [] -ParameterSets: -- Name: (All) - Position: Named - IsRequired: false - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### -HelpVersion - -This parameter allows you to specify the version of the help. The default value is `1.0.0.0`. This -version is written to the `HelpInfo.xml` file that is used for updateable help. - -```yaml -Type: System.Version -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: [] -ParameterSets: -- Name: (All) - Position: Named - IsRequired: false - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### -Locale - -This parameter allows you to specify the language locale for the help files. By default, the cmdlet -uses the current **CultureInfo**. Use the `Get-Culture` cmdlet to see the current culture settings -on your system. - -```yaml -Type: System.String -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: [] -ParameterSets: -- Name: (All) - Position: Named - IsRequired: false - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### -Metadata - -The metadata to add to the frontmatter of the markdown file. The metadata is a hashtable where the -you specify the key and value pairs to add to the frontmatter. New key names are added to the -existing frontmatter. The values of existing keys are overwritten. You can't overwrite the values of -the `document type` or `PlatyPS schema version` keys. If these keys are present in the hashtable, -the cmdlet ignores the values and outputs a warning. - -```yaml -Type: System.Collections.Hashtable -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: [] -ParameterSets: -- Name: (All) - Position: Named - IsRequired: false - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### -OutputFolder - -Specifies the location of where the Markdown module file is written. The cmdlet creates a folder for -each module based on the **CommandHelp** object being processed. - -```yaml -Type: System.String -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: [] -ParameterSets: -- Name: (All) - Position: Named - IsRequired: true - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### -WhatIf - -Shows what would happen if the cmdlet runs. The cmdlet isn't run. - -```yaml -Type: System.Management.Automation.SwitchParameter -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: -- wi -ParameterSets: -- Name: (All) - Position: Named - IsRequired: false - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### CommonParameters - -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, --InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, --ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see -[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). - -## INPUTS - -### Microsoft.PowerShell.PlatyPS.Model.CommandHelp - -## OUTPUTS - -### System.IO.FileInfo - -## NOTES - -## RELATED LINKS - -- [Export-MarkdownModuleFile](Export-MarkdownModuleFile.md) -- [Update-MarkdownModuleFile](Update-MarkdownModuleFile.md) diff --git a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Show-HelpPreview.md b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Show-HelpPreview.md deleted file mode 100644 index a98269f1..00000000 --- a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Show-HelpPreview.md +++ /dev/null @@ -1,172 +0,0 @@ ---- -document type: cmdlet -external help file: Microsoft.PowerShell.PlatyPS-Help.xml -HelpUri: '' -Locale: en-US -Module Name: Microsoft.PowerShell.PlatyPS -ms.custom: OPS13 -ms.date: 10/25/2024 -PlatyPS schema version: 2024-05-01 -title: Show-HelpPreview ---- - -# Show-HelpPreview - -## SYNOPSIS - -View MAML file contents as it would appear when output by `Get-Help`. - -## SYNTAX - -### Path - -``` -Show-HelpPreview [-Path] [-ConvertNotesToList] [-ConvertDoubleDashLists] - [] -``` - -### LiteralPath - -``` -Show-HelpPreview [-LiteralPath] [-ConvertNotesToList] [-ConvertDoubleDashLists] - [] -``` - -## ALIASES - -## DESCRIPTION - -The `Show-HelpPreview` cmdlet displays your generated external help as `Get-Help` output. Specify -one or more files in Microsoft Assistance Markup Language (MAML) format. - -## EXAMPLES - -### Example 1 - Display the contents of a MAML file - -This example displays the contents of PlatyPS MAML file as it would appear when output by -`Get-Help`. - -```powershell -Show-HelpPreview -Path .\Microsoft.PowerShell.PlatyPS\Microsoft.PowerShell.PlatyPS-Help.xml -``` - -## PARAMETERS - -### -ConvertDoubleDashLists - -Indicates that this cmdlet converts double-hyphen list bullets into single-hyphen bullets. -Double-hyphen lists are common in Windows PowerShell documentation. Markdown accepts single-hyphens -for lists. - -```yaml -Type: System.Management.Automation.SwitchParameter -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: [] -ParameterSets: -- Name: (All) - Position: Named - IsRequired: false - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### -ConvertNotesToList - -Indicates that this cmdlet formats multiple paragraph items in the **NOTES** section as single list -items. - -```yaml -Type: System.Management.Automation.SwitchParameter -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: [] -ParameterSets: -- Name: (All) - Position: Named - IsRequired: false - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### -LiteralPath - -Specifies one or more paths to MAML help files. Wildcards aren't supported. - -```yaml -Type: System.String[] -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: -- PSPath -- LP -ParameterSets: -- Name: LiteralPath - Position: 1 - IsRequired: true - ValueFromPipeline: true - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### -Path - -Specifies one or more paths to MAML help files. Wildcards are supported. - -```yaml -Type: System.String[] -DefaultValue: '' -SupportsWildcards: true -ParameterValue: [] -Aliases: [] -ParameterSets: -- Name: Path - Position: 1 - IsRequired: true - ValueFromPipeline: true - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### CommonParameters - -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, --InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, --ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see -[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). - -## INPUTS - -### System.String - -You can pipe path strings to this command. - -## OUTPUTS - -### MamlCommandHelpInfo - -This cmdlet returns a `MamlCommandHelpInfo` objects. This is the same object that is returned by -`Get-Help`. - -## NOTES - -## RELATED LINKS - -- [Get-Help](xref:Microsoft.PowerShell.Core.Get-Help) diff --git a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Test-MarkdownCommandHelp.md b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Test-MarkdownCommandHelp.md deleted file mode 100644 index 1e7aa03a..00000000 --- a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Test-MarkdownCommandHelp.md +++ /dev/null @@ -1,171 +0,0 @@ ---- -document type: cmdlet -external help file: Microsoft.PowerShell.PlatyPS.dll-Help.xml -HelpUri: '' -Locale: en-US -Module Name: Microsoft.PowerShell.PlatyPS -ms.custom: OPS13 -ms.date: 10/25/2024 -PlatyPS schema version: 2024-05-01 -title: Test-MarkdownCommandHelp ---- - -# Test-MarkdownCommandHelp - -## SYNOPSIS - -Tests the structure of a Markdown help file. - -## SYNTAX - -### Item - -``` -Test-MarkdownCommandHelp [-Path] [-DetailView] [] -``` - -### Literal - -``` -Test-MarkdownCommandHelp -LiteralPath [-DetailView] [] -``` - -## ALIASES - -## DESCRIPTION - -This command reads a Markdown help file and validates the structure of the help content by checking -for the presence of required elements in the proper order. The command returns `$true` if the file -passes validation. The **DetailView** parameter can be used to display more detailed validation -information. - -## EXAMPLES - -### Example 1 - Test a Markdown help file - -For this example, we test the structure of a Markdown Module help file. This test fails because the -command expects to test a Markdown Command help file. - -```powershell -Test-MarkdownCommandHelp .\v2\Microsoft.PowerShell.PlatyPS\Microsoft.PowerShell.PlatyPS.md -DetailView -``` - -The output shows the kind of information you can expect from the **DetailView** parameter. - -```Output -Test-MarkdownCommandHelp - Valid: False - File: D:\Git\PS-Src\platyPS\v2docs\v2\Microsoft.PowerShell.PlatyPS\Microsoft.PowerShell.PlatyPS.md - -Messages: - PASS: First element is a thematic break - FAIL: SYNOPSIS not found. - FAIL: SYNTAX not found. - FAIL: DESCRIPTION not found. - FAIL: EXAMPLES not found. - FAIL: PARAMETERS not found. - FAIL: INPUTS not found. - FAIL: OUTPUTS not found. - FAIL: NOTES not found. - FAIL: RELATED LINKS not found. -``` - -## PARAMETERS - -### -DetailView - -Instructs the command to output detailed validation information. - -```yaml -Type: System.Management.Automation.SwitchParameter -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: [] -ParameterSets: -- Name: (All) - Position: Named - IsRequired: false - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### -LiteralPath - -Specifies a path to one or more command markdown files. The value of **LiteralPath** is used exactly -as it's typed. No characters are interpreted as wildcards. If the path includes escape characters, -enclose it in single quotation marks. Single quotation marks tell PowerShell not to interpret any -characters as escape sequences. - -For more information, see -[about_Quoting_Rules](/powershell/module/microsoft.powershell.core/about/about_CommonParameters). - -```yaml -Type: System.String[] -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: -- PSPath -- LP -ParameterSets: -- Name: Literal - Position: Named - IsRequired: true - ValueFromPipeline: false - ValueFromPipelineByPropertyName: true - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### -Path - -The path to the Markdown help file to test. - -```yaml -Type: System.String[] -DefaultValue: '' -SupportsWildcards: true -ParameterValue: [] -Aliases: [] -ParameterSets: -- Name: Item - Position: 0 - IsRequired: true - ValueFromPipeline: true - ValueFromPipelineByPropertyName: true - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### CommonParameters - -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, --InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, --ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see -[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). - -## INPUTS - -### System.String - -## OUTPUTS - -### System.Boolean - -### Microsoft.PowerShell.PlatyPS.MarkdownCommandHelpValidationResult - -## NOTES - -## RELATED LINKS - -- [Export-MarkdownCommandHelp](Export-MarkdownCommandHelp.md) -- [New-MarkdownCommandHelp](New-MarkdownCommandHelp.md) diff --git a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Update-CommandHelp.md b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Update-CommandHelp.md deleted file mode 100644 index 09e46c58..00000000 --- a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Update-CommandHelp.md +++ /dev/null @@ -1,177 +0,0 @@ ---- -document type: cmdlet -external help file: Microsoft.PowerShell.PlatyPS.dll-Help.xml -HelpUri: '' -Locale: en-US -Module Name: Microsoft.PowerShell.PlatyPS -ms.custom: OPS13 -ms.date: 10/25/2024 -PlatyPS schema version: 2024-05-01 -title: Update-CommandHelp ---- - -# Update-CommandHelp - -## SYNOPSIS - -Updates an imported **CommandHelp** object with the information from session cmdlet of the same -name. - -## SYNTAX - -### Path (Default) - -``` -Update-CommandHelp [-Path] [-WhatIf] [-Confirm] [] -``` - -### LiteralPath - -``` -Update-CommandHelp -LiteralPath [-WhatIf] [-Confirm] [] -``` - -## ALIASES - -## DESCRIPTION - -This cmdlet imports a **CommandHelp** object from a Markdown file and updates the object with the -information from the session cmdlet of the same name. The updated object can then be re-exported to -update the source Markdown file. - -## EXAMPLES - -### Example 1 - -```powershell -$mdfiles = Measure-PlatyPSMarkdown -Path .\v1\Microsoft.PowerShell.PlatyPS\*.md -$cmdobj = $mdfiles | Where-Object Filetype -match 'CommandHelp' | - Update-CommandHelp -Path {$_.FilePath} -$cmdobj.count -``` - -```Output -19 -``` - -## PARAMETERS - -### -Confirm - -Prompts you for confirmation before running the cmdlet. - -```yaml -Type: System.Management.Automation.SwitchParameter -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: -- cf -ParameterSets: -- Name: (All) - Position: Named - IsRequired: false - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### -LiteralPath - -Specifies a path to one or more markdown command files. The value of **LiteralPath** is used exactly -as it's typed. No characters are interpreted as wildcards. If the path includes escape characters, -enclose it in single quotation marks. Single quotation marks tell PowerShell not to interpret any -characters as escape sequences. - -For more information, see -[about_Quoting_Rules](/powershell/module/microsoft.powershell.core/about/about_CommonParameters). - -```yaml -Type: System.String[] -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: [] -ParameterSets: -- Name: LiteralPath - Position: Named - IsRequired: true - ValueFromPipeline: true - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### -Path - -Specifies the path to one or more Markdown command file. Wildcard characters are permitted. - -```yaml -Type: System.String[] -DefaultValue: '' -SupportsWildcards: true -ParameterValue: [] -Aliases: [] -ParameterSets: -- Name: Path - Position: 0 - IsRequired: true - ValueFromPipeline: true - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### -WhatIf - -Shows what would happen if the cmdlet runs. The cmdlet isn't run. - -```yaml -Type: System.Management.Automation.SwitchParameter -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: -- wi -ParameterSets: -- Name: (All) - Position: Named - IsRequired: false - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### CommonParameters - -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, --InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, --ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see -[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). - -## INPUTS - -### System.String - -## OUTPUTS - -### Microsoft.PowerShell.PlatyPS.Model.CommandHelp - -## NOTES - -This command is similar to the `Update-MarkdownCommandHelp` cmdlet, but it updates the -**CommandHelp** object in memory instead of updating the source Markdown file. - -## RELATED LINKS - -- [Update-MarkdownCommandHelp](Update-MarkdownCommandHelp.md) diff --git a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Update-MarkdownCommandHelp.md b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Update-MarkdownCommandHelp.md deleted file mode 100644 index 670c7e85..00000000 --- a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Update-MarkdownCommandHelp.md +++ /dev/null @@ -1,218 +0,0 @@ ---- -document type: cmdlet -external help file: Microsoft.PowerShell.PlatyPS.dll-Help.xml -HelpUri: '' -Locale: en-US -Module Name: Microsoft.PowerShell.PlatyPS -ms.custom: OPS13 -ms.date: 10/25/2024 -PlatyPS schema version: 2024-05-01 -title: Update-MarkdownCommandHelp ---- - -# Update-MarkdownCommandHelp - -## SYNOPSIS - -Updates an imported Markdown command file with the information from session cmdlet of the same name. - -## SYNTAX - -### Path (Default) - -``` -Update-MarkdownCommandHelp [-Path] [-NoBackup] [-PassThru] [-WhatIf] [-Confirm] - [] -``` - -### LiteralPath - -``` -Update-MarkdownCommandHelp -LiteralPath [-NoBackup] [-PassThru] [-WhatIf] [-Confirm] - [] -``` - -## ALIASES - -## DESCRIPTION - -This cmdlet imports a **CommandHelp** object from a Markdown file and updates the object with the -information from the session cmdlet of the same name, then rewrites the Markdown file with the -updated information. - -## EXAMPLES - -### Example 1 - -```powershell -$mdfiles = Measure-PlatyPSMarkdown -Path .\v1\Microsoft.PowerShell.PlatyPS\*.md -$mdfiles | Where-Object Filetype -match 'CommandHelp' | - Update-MarkdownCommandHelp -Path {$_.FilePath} -``` - -## PARAMETERS - -### -Confirm - -Prompts you for confirmation before running the cmdlet. - -```yaml -Type: System.Management.Automation.SwitchParameter -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: -- cf -ParameterSets: -- Name: (All) - Position: Named - IsRequired: false - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### -LiteralPath - -Specifies a path to one or more markdown command files. The value of **LiteralPath** is used exactly -as it's typed. No characters are interpreted as wildcards. If the path includes escape characters, -enclose it in single quotation marks. Single quotation marks tell PowerShell not to interpret any -characters as escape sequences. - -For more information, see -[about_Quoting_Rules](/powershell/module/microsoft.powershell.core/about/about_CommonParameters). - -```yaml -Type: System.String[] -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: [] -ParameterSets: -- Name: LiteralPath - Position: Named - IsRequired: true - ValueFromPipeline: true - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### -NoBackup - -By default, the cmdlet creates a backup of the original Markdown file before updating it. Use this -parameter to suppress the creation of the backup file. - -```yaml -Type: System.Management.Automation.SwitchParameter -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: [] -ParameterSets: -- Name: (All) - Position: Named - IsRequired: false - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### -PassThru - -By default, this cmdlet doesn't generate any output. Use this parameter to return the updated file -object. - -```yaml -Type: System.Management.Automation.SwitchParameter -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: [] -ParameterSets: -- Name: (All) - Position: Named - IsRequired: false - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### -Path - -Specifies the path to one or more Markdown command file. Wildcard characters are permitted. - -```yaml -Type: System.String[] -DefaultValue: '' -SupportsWildcards: true -ParameterValue: [] -Aliases: [] -ParameterSets: -- Name: Path - Position: 0 - IsRequired: true - ValueFromPipeline: true - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### -WhatIf - -Shows what would happen if the cmdlet runs. The cmdlet isn't run. - -```yaml -Type: System.Management.Automation.SwitchParameter -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: -- wi -ParameterSets: -- Name: (All) - Position: Named - IsRequired: false - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### CommonParameters - -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, --InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, --ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see -[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). - -## INPUTS - -### System.String - -## OUTPUTS - -### System.IO.FileInfo - -## NOTES - -This command is similar to the `Update-CommandHelp` cmdlet, but it updates the source Markdown file. - -## RELATED LINKS - -- [Update-CommandHelp](Update-CommandHelp.md) diff --git a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Update-MarkdownModuleFile.md b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Update-MarkdownModuleFile.md deleted file mode 100644 index e5e8a8d2..00000000 --- a/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Update-MarkdownModuleFile.md +++ /dev/null @@ -1,382 +0,0 @@ ---- -document type: cmdlet -external help file: Microsoft.PowerShell.PlatyPS.dll-Help.xml -HelpUri: '' -Locale: en-US -Module Name: Microsoft.PowerShell.PlatyPS -ms.custom: OPS13 -ms.date: 10/25/2024 -PlatyPS schema version: 2024-05-01 -title: Update-MarkdownModuleFile ---- - -# Update-MarkdownModuleFile - -## SYNOPSIS - -Updates the Markdown module file. - -## SYNTAX - -### path - -``` -Update-MarkdownModuleFile [-Path] [-CommandHelp] [-Encoding ] - [-Force] [-HelpUri ] [-HelpInfoUri ] [-HelpVersion ] [-Locale ] - [-Metadata ] [-NoBackup] [-WhatIf] [-Confirm] [] -``` - -### literalpath - -``` -Update-MarkdownModuleFile [-CommandHelp] -LiteralPath - [-Encoding ] [-Force] [-HelpUri ] [-HelpInfoUri ] - [-HelpVersion ] [-Locale ] [-Metadata ] [-NoBackup] [-WhatIf] - [-Confirm] [] -``` - -## ALIASES - -## DESCRIPTION - -This cmdlet updates a Markdown module file with **CommandHelp** object information imported from -Markdown command files. - -## EXAMPLES - -### Example 1 - Update a module file from new command help files - -```powershell -$mdfiles = Measure-PlatyPSMarkdown -Path .\Microsoft.PowerShell.PlatyPS\*.md -$mdfiles | Where-Object Filetype -match 'CommandHelp' | - Import-MarkdownCommandHelp -Path {$_.FilePath} | - Update-MarkdownModuleFile -Path .\Microsoft.PowerShell.PlatyPS\Microsoft.PowerShell.PlatyPS.md -``` - -## PARAMETERS - -### -CommandHelp - -The **CommandHelp** objects to export. You can pass the **CommandHelp** object on the pipeline or by -using this parameter. - -```yaml -Type: Microsoft.PowerShell.PlatyPS.Model.CommandHelp[] -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: [] -ParameterSets: -- Name: (All) - Position: 1 - IsRequired: true - ValueFromPipeline: true - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### -Confirm - -Prompts you for confirmation before running the cmdlet. - -```yaml -Type: System.Management.Automation.SwitchParameter -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: -- cf -ParameterSets: -- Name: (All) - Position: Named - IsRequired: false - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### -Encoding - -The encoding to use when writing the markdown file. If no value is specified, encoding defaults to -the value of the `$OutputEncoding` preference variable. - -```yaml -Type: System.Text.Encoding -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: [] -ParameterSets: -- Name: (All) - Position: Named - IsRequired: false - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### -Force - -Use the **Force** parameter to overwrite the output file if it already exists. - -```yaml -Type: System.Management.Automation.SwitchParameter -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: [] -ParameterSets: -- Name: (All) - Position: Named - IsRequired: false - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### -HelpInfoUri - -This parameter allows you to specify the URI used for updateable help. By default, the cmdlet uses -the HelpInfoUri specified in the module manifest. - -```yaml -Type: System.String -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: [] -ParameterSets: -- Name: (All) - Position: Named - IsRequired: false - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### -HelpUri - -{{ Fill HelpUri Description }} - -```yaml -Type: System.String -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: [] -ParameterSets: -- Name: (All) - Position: Named - IsRequired: false - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### -HelpVersion - -This parameter allows you to specify the version of the help. The default value is `1.0.0.0`. This -version is written to the `HelpInfo.xml` file that is used for updateable help. - -```yaml -Type: System.Version -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: [] -ParameterSets: -- Name: (All) - Position: Named - IsRequired: false - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### -LiteralPath - -Specifies a path to one or more module markdown files. The value of **LiteralPath** is used exactly -as it's typed. No characters are interpreted as wildcards. If the path includes escape characters, -enclose it in single quotation marks. Single quotation marks tell PowerShell not to interpret any -characters as escape sequences. - -For more information, see -[about_Quoting_Rules](/powershell/module/microsoft.powershell.core/about/about_CommonParameters). - -```yaml -Type: System.String -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: [] -ParameterSets: -- Name: literalpath - Position: Named - IsRequired: true - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### -Locale - -This parameter allows you to specify the language locale for the help files. By default, the cmdlet -uses the current **CultureInfo**. Use the `Get-Culture` cmdlet to see the current culture settings -on your system. - -```yaml -Type: System.String -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: [] -ParameterSets: -- Name: (All) - Position: Named - IsRequired: false - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### -Metadata - -The metadata to add to the frontmatter of the markdown file. The metadata is a hashtable where the -you specify the key and value pairs to add to the frontmatter. New key names are added to the -existing frontmatter. The values of existing keys are overwritten. You can't overwrite the values of -the `document type` or `PlatyPS schema version` keys. If these keys are present in the hashtable, -the cmdlet ignores the values and outputs a warning. - -```yaml -Type: System.Collections.Hashtable -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: [] -ParameterSets: -- Name: (All) - Position: Named - IsRequired: false - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### -NoBackup - -By default, the cmdlet creates a backup of the original Markdown file before updating it. Use this -parameter to suppress the creation of the backup file. - -```yaml -Type: System.Management.Automation.SwitchParameter -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: [] -ParameterSets: -- Name: (All) - Position: Named - IsRequired: false - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### -Path - -Specifies a path to one or more module markdown files. - -```yaml -Type: System.String -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: [] -ParameterSets: -- Name: path - Position: 0 - IsRequired: true - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### -WhatIf - -Shows what would happen if the cmdlet runs. The cmdlet isn't run. - -```yaml -Type: System.Management.Automation.SwitchParameter -DefaultValue: '' -SupportsWildcards: false -ParameterValue: [] -Aliases: -- wi -ParameterSets: -- Name: (All) - Position: Named - IsRequired: false - ValueFromPipeline: false - ValueFromPipelineByPropertyName: false - ValueFromRemainingArguments: false -DontShow: false -AcceptedValues: [] -HelpMessage: '' -``` - -### CommonParameters - -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, --InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, --ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see -[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). - -## INPUTS - -### Microsoft.PowerShell.PlatyPS.Model.CommandHelp - -## OUTPUTS - -### System.IO.FileInfo - -## NOTES - -## RELATED LINKS - -- [New-MarkdownModuleFile](New-MarkdownModuleFile.md) diff --git a/docs/developer/Microsoft.PowerShell.PlatyPS/CONTRIBUTING.md b/docs/developer/Microsoft.PowerShell.PlatyPS/CONTRIBUTING.md deleted file mode 100644 index 0e9a5bee..00000000 --- a/docs/developer/Microsoft.PowerShell.PlatyPS/CONTRIBUTING.md +++ /dev/null @@ -1,53 +0,0 @@ -# Contributing to platyPS - -## Get the code - -``` -git clone https://github.com/PowerShell/platyPS -``` - -## Understand code layout - -TBD - -## Build - -To build the whole project, use the `build.ps1` helper script. It depends on the -[dotnet cli](https://docs.microsoft.com/en-us/dotnet/core/tools/) build tool. - -On Windows you would also need to -[install full dotnet framework](https://docs.microsoft.com/en-us/dotnet/framework/install/guide-for-developers) -if it's not installed already. - -```powershell -.\build.ps1 -``` - -As part of the build, platyPS generates help for itself. The output of the build is placed in -`out\Microsoft.PowerShell.PlatyPS`. - -`build.ps1` also imports the module from `out\platyPS` and generates help itself. - -> [!NOTE] -> If you changed C# code, `build.ps1` will try to overwrite a DLL in use. You will then need to -> re-open your PowerShell session. If you know a better workflow, please suggest it in the Issues. - -## Tests - -Each part of the project has a test set: - -- The C# part has xUnit tests. -- The PowerShell part has [Pester](https://github.com/pester/Pester) tests. You can run them with - `Invoke-Pester`. - -> [!NOTE] -> Pester tests always force-import the module from the output location of `.\build.ps1`. - -## Schema - -If you have ideas or concerns about the Markdown schema, feel free to open a GitHub Issue to discuss -it. - -## Repo structure - -TBD diff --git a/docs/developer/Microsoft.PowerShell.PlatyPS/specs/PlatyPS-Design-Notes.md b/docs/developer/Microsoft.PowerShell.PlatyPS/specs/PlatyPS-Design-Notes.md deleted file mode 100644 index 4c0cc2ce..00000000 --- a/docs/developer/Microsoft.PowerShell.PlatyPS/specs/PlatyPS-Design-Notes.md +++ /dev/null @@ -1,147 +0,0 @@ ---- -ms.date: 10/22/2024 ---- -# Microsoft.PowerShell.PlatyPS design notes - -## Design notes - -### Features/Functionality - -- When PlatyPS writes file output, it should create folder structure of module-named folders - containing cmdlet markdown for the cmdlets in those modules -- PlatyPS should populate the markdown with all the facts that it can reasonably gather about the - command: - - Name - - Syntax of all parameter sets - - Parameter names and metadata (type, all attributes, etc. arranged by parameter set) - - Common parameters (if supported) - - Input types - types that can be piped to the command - - Output types - as defined by the cmdlet attributes -- PlatyPS should insert placeholder text for all content that must be provided by the author - -### Module notes - -- Total rewrite in C# to improve performance, object model, and extensibility - - Cmdlets are focused on the object model and provide a single purpose - - Chain cmdlets in a pipeline to perform complex operations - - Workflow style cmdlets will be script-based to improve usability for authors - - Script-based provide readable code model that allows end-users to customize their own - workflows as needed - - Workflows are easier to code in script rather than in C# -- Total breaking change from previous versions -- New module name - Microsoft.PowerShell.PlatyPS - - Allows you to install side-by-side with previous versions - - No common cmdlet names between modules - - No intent to provide proxies for old cmdlets -- Cmdlet names better reflect what they do - - Import-SomeFormat - - Export-SomeFormat -- New markdown parsing and rendering powered by markdig -- Module provides Yaml output to be used by the Learn reference pipeline -- Object model is the heart of the new module - - Establishes a common object model for cmdlets and module files - - Markdown is the source of truth for the documentation - - Cmdlets import the markdown in the the CommandHelp object model - - CommandHelp objects can be exported to Markdown, Yaml, or MAML - - CommandHelp objects can be imported from Markdown, Yaml, or MAML - - Conversion to/from MAML is lower fidelity other formats - results in loss of data and accuracy - of the documentation - -### Markdown notes - -- Markdown is the source of truth for the documentation -- Markdown has a strict H2/H3 structure - - You can't add headers or reorder them - - Not all H2/H3 sections require content. The H2/H3 line is required, but the content is optional. - This is done to ensure that the markdown structure is consistent with the object model. -- Metadata names have been changed to match PowerShell property names and common terminology. - - This causes less confusion for authors and makes it easier to troubleshoot validation and - rendering issues -- Import command can read old (0.14) format or new format and converts Markdown into CommandHelp - object -- Export commands convert CommandHelp object into other formats - - Export to markdown command can writes new markdown format - - Export to Yaml is used by the Learn reference pipeline and reflects the new object model - - Export to MAML is lower fidelity and results in loss of data and accuracy of the documentation - due to limitation in Get-Help and the MAML specification -- The Yaml frontmatter is used to store metadata that is not part of the markdown content - - The object model has a set of required key/value pairs - - The `document type` and `PlatyPS schema version` keys are inviolate (cannot be changed) - - You can add custom metadata to the frontmatter - - Any key/value pairs not managed by PlatyPS are passed through unaltered - -### Authoring process - -- Authoring is always a manual process requiring human intervention -- PlatyPS helps automate the process and provides a consistent structure for the documentation but - can't fill in descriptions, examples, or related links - - PlatyPS inserts placeholder text to show you where to add content -- Authors must review and edit the markdown files to ensure that the content is accurate for every - authoring step - - Creating new markdown for new modules/commands - - Migrating existing markdown to the new format - - Updating existing markdown based on new versions of modules/commands - -### Converting to/from other formats - -- Markdown is the source of truth for the documentation -- Converting from the old Markdown format to the new format is a one-way process - - The new format has more structure and metadata than the old format - - The new format is more consistent and easier to validate - - The old format does not reflect all of the correct facts about parameters - - Converting from the old to the new format does not improve the accuracy of the parameter - metadata; you must run the update process -- The update process requires that the commands/modules be available in the current session so - that the complete parameter metadata can be discovered -- Converting to Yaml - - There is no loss of fidelity when converting from the Markdown to Yaml (or vice versa) - - The Yaml is just a serialization of the CommandHelp object model - - All properties are preserved even if the value is null - - Rendering to HTML should handle null values gracefully (e.g. conditional formatting to omit null - values) -- Converting to/from MAML - - There is a loss of fidelity when converting to MAML due to limitations in the MAML specification - and Get-Help cmdlet -- Importing from MAML is supported as a method of last resort. - -## Frontmatter - -| FileType | v1 Key | v1 Status | v2 key | v2 Status | -|----------|--------------------|-----------------------------------------------------|------------------------|----------------------------------------------------| -| cmdlet | | n/a | document type | Required | -| cmdlet | external help file | Required - unique to cmdlet | external help file | Required | -| cmdlet | online version | Key required, value can be null - unique to cmdlet | HelpUri | Key required, value can be null - unique to cmdlet | -| cmdlet | Locale | Required | Locale | Required | -| cmdlet | Module Name | Key required, value can be null | Module Name | Key required, value can be null | -| cmdlet | ms.date | Optional | ms.date | Optional | -| cmdlet | schema | Required | PlatyPS schema version | Required | -| cmdlet | title | Required | title | Required | -| cmdlet | | n/a | aliases | Optional | -| module | | n/a | document type | Required | -| module | Help Version | Key required, value can be null - unique to module | Help Version | Key required, value can be null - unique to module | -| module | Download Help Link | Key required, value can be null - unique to module | HelpInfoUri | Key required, value can be null - unique to module | -| module | Locale | Required | Locale | Required | -| module | Module Guid | Required - unique to module | Module Guid | Required - unique to module | -| module | Module Name | Required | Module Name | Required | -| module | ms.date | Optional | ms.date | Optional | -| module | schema | Required | PlatyPS schema version | Required | -| module | title | Required | title | Required | - -## Scenarios to support OPS - -1. Workflow script to convert all markdown files to YAML in a folder -1. Workflow script for CabGen -1. Make rendering decisions for HTML presentation - -These items to be done by Sean and Jason working with DanniX and team. - -## Future ideas - -- Create a method to convert CommandHelp object to the Get-Help object model - - This could be an easy way to ship markdown instead of MAML for downlevel systems that don't have - or cant support Help v2. -- Add commands to stream conversion to Markdown to support Markdown rendering in the console (e.g. - pipe to `glow.exe`) -- Create workflow convenience scripts to include in module -- Compare-MarkdownCommandHelp - can't compare module files - diff --git a/docs/developer/Microsoft.PowerShell.PlatyPS/specs/PowerShellCmdlet.schema.json b/docs/developer/Microsoft.PowerShell.PlatyPS/specs/PowerShellCmdlet.schema.json deleted file mode 100644 index 8636f27e..00000000 --- a/docs/developer/Microsoft.PowerShell.PlatyPS/specs/PowerShellCmdlet.schema.json +++ /dev/null @@ -1,215 +0,0 @@ -{ - "title": "PowershellCmdlet", - "$schema": "https://dotnet.github.io/docfx/schemas/v1.0/schema.json#", - "version": "1.0.0", - "description": "The schema for powershell cmdlet page", - "id": "https://static.docs.com/ui/latest/schemas/PowershellCmdlet.schema.json", - "type": "object", - "additionalProperties": false, - "required": ["name", "module", "uid"], - "renderType": "content", - "archivable": false, - "properties": { - "applicable": { - "items": { - "type": "string" - }, - "minItems": 1, - "type": "array" - }, - "description": { - "type": "string", - "contentType": "markdown", - "tags": ["localizable"] - }, - "examples": { - "items": { - "additionalProperties": false, - "required": ["title", "summary", "description"], - "properties": { - "title": { - "type": "string", - "tags": ["localizable"] - }, - "summary": { - "type": "string", - "contentType": "markdown", - "tags": ["localizable"] - }, - "code": { - "type": "string" - }, - "description": { - "type": "string", - "contentType": "markdown", - "tags": ["localizable"] - } - }, - "type": "object" - }, - "minItems": 1, - "type": "array" - }, - "inputs": { - "items": { - "additionalProperties": false, - "required": ["name", "description"], - "properties": { - "name": { - "type": "string", - "contentType": "markdown" - }, - "description": { - "type": "string", - "contentType": "markdown", - "tags": ["localizable"] - } - }, - "type": "object" - }, - "minItems": 1, - "type": "array" - }, - "links": { - "items": { - "additionalProperties": false, - "required": ["href", "text"], - "properties": { - "href": { - "type": "string", - "contentType": "href" - }, - "text": { - "type": "string", - "tags": ["localizable"] - } - }, - "type": "object" - }, - "minItems": 1, - "type": "array" - }, - "metadata": { - "properties": { - "description": { - "type": "string", - "tags": ["localizable"] - }, - "title": { - "type": "string", - "tags": ["localizable"] - } - }, - "type": "object" - }, - "module": { - "type": "string", - "contentType": "xref" - }, - "name": { - "type": "string" - }, - "notes": { - "type": "string", - "contentType": "markdown", - "tags": ["localizable"] - }, - "outputs": { - "items": { - "additionalProperties": false, - "required": ["name", "description"], - "properties": { - "name": { - "type": "string", - "contentType": "markdown" - }, - "description": { - "type": "string", - "contentType": "markdown", - "tags": ["localizable"] - } - }, - "type": "object" - }, - "minItems": 1, - "type": "array" - }, - "parameters": { - "items": { - "additionalProperties": false, - "required": ["name", "description", "type", "position"], - "properties": { - "name": { - "type": "string" - }, - "summary": { - "type": "string", - "contentType": "markdown", - "tags": ["localizable"] - }, - "description": { - "type": "string", - "contentType": "markdown", - "tags": ["localizable"] - }, - "isRequired": { - "type": "boolean" - }, - "applicable": { - "items": { - "type": "string" - }, - "minItems": 1, - "type": "array" - }, - "type": { - "type": "string", - "contentType": "markdown" - }, - "aliases": { - "type": "string" - }, - "parameterValueGroup": { - "type": "string" - }, - "position": { - "type": "string" - }, - "defaultValue": { - "type": "string" - }, - "pipelineInput": { - "type": "boolean" - }, - "acceptWildcardCharacters": { - "type": "boolean" - }, - "valueFrom": { - "type": "string" - } - }, - "type": "object" - }, - "minItems": 1, - "type": "array" - }, - "summary": { - "type": "string", - "contentType": "markdown", - "tags": ["localizable"] - }, - "syntaxes": { - "items": { - "type": "string" - }, - "minItems": 1, - "type": "array" - }, - "uid": { - "type": "string", - "contentType": "uid" - } - }, - "metadata": "/metadata", - "xrefProperties": ["name", "summary"] -} diff --git a/docs/developer/Microsoft.PowerShell.PlatyPS/specs/PowershellCmdletV2.schema.json b/docs/developer/Microsoft.PowerShell.PlatyPS/specs/PowershellCmdletV2.schema.json deleted file mode 100644 index 2e9e70c1..00000000 --- a/docs/developer/Microsoft.PowerShell.PlatyPS/specs/PowershellCmdletV2.schema.json +++ /dev/null @@ -1,257 +0,0 @@ -{ - "title": "PowershellCmdletV2", - "$schema": "https://dotnet.github.io/docfx/schemas/v1.0/schema.json#", - "version": "1.0.0", - "description": "The schema for powershell cmdlet page - version 2", - "id": "https://static.docs.com/ui/latest/schemas/PowershellCmdletV2.schema.json", - "type": "object", - "additionalProperties": false, - "required": ["name", "module", "uid"], // tend to only keep necessary items for OPS, may validate the rest through Docs.Validation service by contacting Megan Bradley - "renderType": "content", - "archivable": false, - "properties": { - "aliases": { - "type": "string", - "contentType": "markdown", - "tags": ["localizable"] - }, - "applicable": { - "items": { - "type": "string" - }, - "minItems": 1, - "type": "array" - }, - "description": { - "type": "string", - "contentType": "markdown", - "tags": ["localizable"] - }, - "examples": { // Remove something. For fixing the mixture of code and output, PlatyPS issue #576. This change should take effect along with or after integrating PlatyPS v2 New-YamlHelp, because current MAML2YAML generates summary from content. - "items": { - "additionalProperties": false, - "required": ["title", "description"], - "properties": { - "title": { - "type": "string", - "tags": ["localizable"] - }, - "description": { - "type": "string", - "contentType": "markdown", - "tags": ["localizable"] - } - }, - "type": "object" - }, - "minItems": 1, - "type": "array" - }, - "inputs": { - "items": { - "additionalProperties": false, - "required": ["name", "description"], - "properties": { - "name": { - "type": "string", - "contentType": "markdown" - }, - "description": { - "type": "string", - "contentType": "markdown", - "tags": ["localizable"] - } - }, - "type": "object" - }, - "minItems": 1, - "type": "array" - }, - "links": { - "items": { - "additionalProperties": false, - "required": ["href", "text"], - "properties": { - "href": { - "type": "string", - "contentType": "href" - }, - "text": { - "type": "string", - "tags": ["localizable"] - } - }, - "type": "object" - }, - "minItems": 1, - "type": "array" - }, - "metadata": { - "properties": { - "description": { - "type": "string", - "tags": ["localizable"] - }, - "title": { - "type": "string", - "tags": ["localizable"] - } - }, - "type": "object" - }, - "module": { - "type": "string", - "contentType": "xref" - }, - "name": { - "type": "string" - }, - "notes": { - "type": "string", - "contentType": "markdown", - "tags": ["localizable"] - }, - "outputs": { - "items": { - "additionalProperties": false, - "required": ["name", "description"], - "properties": { - "name": { - "type": "string", - "contentType": "markdown" - }, - "description": { - "type": "string", - "contentType": "markdown", - "tags": ["localizable"] - } - }, - "type": "object" - }, - "minItems": 1, - "type": "array" - }, - "parameters": { // Add & modify something. This change should take effect along with or after integrating PlatyPS v2 New-YamlHelp, because current MAML2YAML does not transform commonParameters into yaml from markdown. - "properties": { - "cmdletParameters": { // naming pending? use only a single word as the name if possible - "items": { - "additionalProperties": false, - "required": ["name", "description", "type", "parameterSet"], - "properties": { - "name": { - "type": "string" - }, - "description": { - "type": "string", - "contentType": "markdown", - "tags": ["localizable"] - }, - "type": { - "type": "string", - "contentType": "markdown" - }, - "parameterSet" : { - "items": { - "type": "array", - "minItems": 1, - "additionalProperties": false, - "required": [ "name" ], - "properties": { - "name": { - "type": "string" - }, - "position": { - "type": "string" - }, - "valueByPipeline": { - "type": "boolean" - }, - "valueByPipelineByPropertyName": { - "type": "boolean" - }, - "valueFromRemainingArguments": { - "type": "boolean" - }, - "isRequired": { // mandatory - "type": "boolean" - } - } - } - }, - "applicable": { // ???? - "items": { - "type": "string" - }, - "minItems": 1, - "type": "array" - }, - "aliases": { - "type": "array", - "minItems": 1, - "items": { - "type": "string" - } - }, - "isDynamic": { - "type": "boolean" - }, - "allowedValues": { // parameterValueGroup - "items": { - "type": "string" - }, - "minItems": 1, - "type": "array" - }, - "defaultValue": { - "type": "string" - }, - "acceptWildcardCharacters": { - "type": "boolean" - }, - "confirmImpact": { - "type": "string" - } - }, - "type": "object" - }, - "minItems": 1, - "type": "array" - }, - "commonParameters": { // This implies has cmdlet binding - "type": "string", - "contentType": "markdown", - "tags": ["localizable"] - } - }, - "type": "object" - }, - "summary": { - "type": "string", - "contentType": "markdown", - "tags": ["localizable"] - }, - "syntaxes": { // Change type and add properties. This change should take effect along with or after integrating PlatyPS v2 New-YamlHelp, because current MAML2YAML generates text for this part. - "items": { - "additionalProperties": false, - "required": ["parameterSetName", "syntax"], - "properties": { - "parameterSetName": { - "type": "string" - }, - "syntax": { // naming pending? use only a single word as the name if possible - "type": "string" - } - }, - "type": "object" - }, - "minItems": 1, - "type": "array" - }, - "uid": { - "type": "string", - "contentType": "uid" - } - }, - "metadata": "/metadata", - "xrefProperties": ["name", "summary"] -} diff --git a/docs/developer/Microsoft.PowerShell.PlatyPS/specs/Schema-Notes.md b/docs/developer/Microsoft.PowerShell.PlatyPS/specs/Schema-Notes.md deleted file mode 100644 index 2c279340..00000000 --- a/docs/developer/Microsoft.PowerShell.PlatyPS/specs/Schema-Notes.md +++ /dev/null @@ -1,135 +0,0 @@ -This the current layout of the markdown for a Cmdlet with notes: - -YAML Frontmatter - -- Need to not error on PlatyPS required keys (external help file, Locale, Module Name, ms.date, - online version, schema, title) -- What should we do about description? - currently copied by OPS from Description below -- Mapping to existing JSON schema: properties/metadata - -Title - -- Type: H1 -- Required: Y -- Count: 1 -- Mapping to existing JSON schema: properties/name - -Synopsis - -- Type: H2 -- Required: Y -- Count: 1 -- Mapping to existing JSON schema: properties/summary - -Syntax - -- Type: H2 -- Required: Y -- Count: 1 -- Required: No changes -- Mapping to existing JSON schema: properties/syntaxes -- Notes: Contains 1 or more of the following: - - Parameter Set name - - Type: H3 - - Required: Y - - Count: 1-N - - Parameter Sets - should be sorted starting with Default, then by Alpha -- Parameters (in syntax block) - - Syntax block - - What format do you want? - Currently MAML2Yaml is using the strings from the code block instead - of a Yaml data model. Prefer the string model. - -Description - -- Type: H2 -- Required: Y -- Count: 1 -- Mapping to existing JSON schema: properties/description -- Allow any markdown content type except Headers - -Examples - -- Type: H2 -- Required: Y -- Count: 1 -- Mapping to existing JSON schema: properties/examples -- Notes: Contains 1 or more of the following - - Example - - Type: H3 - - Required: Y - - Count: 1-N - - Should require one code block at minimum per example - - Should allow a mix of markdown code blocks and paragraphs in any order - -Parameters - -- Type: H2 -- Required: Y -- Count: 1 -- Mapping to existing JSON schema: properties/parameters -- Parameters should be sorted Alphabetically followed by `-Confirm` and `-WhatIf` (when included). - PlatyPS has the `-AlphabeticParamsOrder` parameter that produces this order. -- Notes: Contains 1 or more of the following - - Parameter - - Type: H3 - - Required: Y - - Count: 1-N - - Required: Yaml block should include: - - Parameter Set Name - - Position can be different per parameter set - - Add **AcceptedValues** - Should display enumerated values of parameter (like ValidateSet) - - maps to properties/parameters/parameterValueGroup? - - Add **ConfirmImpact** - Impact severity should be reflected and displayed to inform defaults - for `-Confirm` - - what is **valueFrom** in JSON schema? - - **pipelineInput** is currently a boolean. The value can be different per parameter set to - the type needs to be a string - -Common Parameters - -- Type: H3 -- Required: Y -- Count: 1 -- Notes: - - this is missing from the schema - need to define it - - The content should be the markdown description provided in the file - -Inputs - -- Type: H2 -- Required: Y -- Count: 1 -- Mapping to existing JSON schema: properties/inputs -- Notes: Contains 0 or more of the following: - - Input type - - Type: H3 - - Required: N - - Count: 0-N - -Outputs - -- Type: H2 -- Required: Y -- Count: 1 -- Mapping to existing JSON schema: properties/outputs -- Notes: Contains 0 or more of the following: - - Output type - - Type: H3 - - Required: N - - Count: 0-N - -Notes - -- Type: H2 -- Required: N -- Mapping to existing JSON schema: properties/notes -- Count: 1 header with 0 or more markdown elements (excluding header types) - -Related links - -- Type: H3 -- Required: Y -- Count: 1 -- Mapping to existing JSON schema: properties/links -- Link list should use a bullet list -- Should support markdown paragraphs not just links diff --git a/docs/developer/Microsoft.PowerShell.PlatyPS/specs/alias-prototype.md b/docs/developer/Microsoft.PowerShell.PlatyPS/specs/alias-prototype.md deleted file mode 100644 index 9da66a77..00000000 --- a/docs/developer/Microsoft.PowerShell.PlatyPS/specs/alias-prototype.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -external help file: Microsoft.PowerShell.Commands.Management.dll-Help.xml -Locale: en-US -Module Name: Microsoft.PowerShell.Management -ms.date: 12/05/2023 -online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.management/get-childitem?view=powershell-7.2&WT.mc_id=ps-gethelp -schema: 2.0.0 -title: Get-ChildItem -alias: [dir, gci, ls] ---- -# Get-ChildItem - -## SYNOPSIS - -Gets the items and child items in one or more specified locations. - -## ALIASES - -PowerShell includes the following aliases for `Get-ChildItem`: - -- All platforms: `dir`, `gci` -- Windows: `ls` - -## SYNTAX - -### Items (Default) - -``` -Get-ChildItem [[-Path] ] [[-Filter] ] [-Include ] [-Exclude ] - [-Recurse] [-Depth ] [-Force] [-Name] [-Attributes ] - [-FollowSymlink] [-Directory] [-File] [-Hidden] [-ReadOnly] [-System] [] -``` - -### LiteralItems - -``` -Get-ChildItem [[-Filter] ] -LiteralPath [-Include ] - [-Exclude ] [-Recurse] [-Depth ] [-Force] [-Name] - [-Attributes ] [-FollowSymlink] [-Directory] [-File] [-Hidden] - [-ReadOnly] [-System] [] -``` diff --git a/docs/developer/Microsoft.PowerShell.PlatyPS/specs/platyps_2.0_about_schema.md b/docs/developer/Microsoft.PowerShell.PlatyPS/specs/platyps_2.0_about_schema.md deleted file mode 100644 index 6d16b18e..00000000 --- a/docs/developer/Microsoft.PowerShell.PlatyPS/specs/platyps_2.0_about_schema.md +++ /dev/null @@ -1,22 +0,0 @@ -# Schema for About_ files - -The following sections outline schema changes for the About_ file. - -| Heading | Level | Required? | Count | Description | -| ----------------- | ----- | --------- | ----- | ------------------------------------------------------------------------------------------------------------------------- | -| Title | H1 | Y | 1 | - Title should be Sentence Case - About Topic
- Title meta data 'about_' should match the file basename | -| Short Description | H2 | Y | 1 | - Should be Sentence Case | -| Long Description | H2 | Y | 1 | - Should be Sentence case
- Should allow multiple Long description subtopics
- Should support subtopics at H3 or H2 | -| See Also | H2 | Y | 1 | - This is required but may be empty | - -General notes - -- Should be rendered as plain text compatible with `Get-Help` -- `Get-Help` bug:Synopsis -- [Get-Help bug][05] -- Add switch to provide Cabs or Zips. Default: cabs -- Add switch to include markdown Default: off -- About_ schema does not say anything about line wrapping etc. - - If left as text files, then wrap at 80 columns. - - But if converted to schema-based line limit isn't a problem (for the future). Still a problem - for previous versions. diff --git a/docs/developer/Microsoft.PowerShell.PlatyPS/specs/platyps_2.0_cmdlets.md b/docs/developer/Microsoft.PowerShell.PlatyPS/specs/platyps_2.0_cmdlets.md deleted file mode 100644 index 33aeb0d2..00000000 --- a/docs/developer/Microsoft.PowerShell.PlatyPS/specs/platyps_2.0_cmdlets.md +++ /dev/null @@ -1,158 +0,0 @@ -## PlatyPS Cmdlets and Parameters - -PlatyPS includes a set of cmdlets with parameters. - -The following section is a review of the cmdlets for changes to the parameters and their defaults. -We need to decide to what cmdlets and features to keep. We should make a list breaking changes for -documentation. - -In case of breaking changes, do we need a legacy mode? - -- We don't know until we see what all the breaking changes are -- If we make changes that require changes to Get-Help we will need something that targets a older - versions PowerShell. - -#### Get-HelpPreview - -| ParamName | DefaultValue | Description | -| ---------------------- | ------------ | ------------------------------------------------------------------------------------------ | -| Path | None | Specifies an array of paths of MAML external help files | -| ConvertNotesToList | False | Indicates that this cmldet formats multiple paragraph items in the NOTES section as single | -| ConvertDoubleDashLists | False | Indicates that this cmldet converts double-hyphen list bullets into single-hyphen bullets | - -#### Get-MarkdownMetadata - -| ParamName | DefaultValue | Description | -| --------- | ------------ | -------------------------------------------------------- | -| Path | None | Specifies an array of paths of markdown files or folders | -| Markdown | None | Specifies a string that contains markdown formatted text | - -#### Merge-MarkdownHelp - -| ParamName | DefaultValue | Description | -| ----------------------- | ---------------- | ------------------------------------------------------------------------------------- | -| Encoding | UTF8 without BOM | Specifies the character encoding for your external help file. Specify a System.Text.E | -| ExplicitApplicableIfAll | False | Always write out full list of applicable tags. By default cmdlets and parameters that | -| Force | False | Indicates that this cmdlet overwrites an existing file that has the same name | -| MergeMarker | '!!! ' | String to be used as a merge text indicator. Applicable tag list would be included | -| OutputPath | None | Specifies the path of the folder where this cmdlet creates the combined markdown help | -| Path | None | Specifies an array of paths of markdown files or folders. This cmdlet creates | - -#### New-ExternalHelp - -| ParamName | DefaultValue | Description | -| ------------- | ---------------- | ----------------------------------------------------------------------------------------------- | -| OutputPath | None | Specifies the path of a folder where this cmdlet saves your external help file. The folder name | -| Encoding | UTF8 without BOM | Specifies the character encoding for your external help file. Specify a System.Text.Encoding | -| Force | False | Indicates that this cmdlet overwrites an existing file that has the same name | -| Path | None | Specifies an array of paths of markdown files or folders. This cmdlet creates external help | -| ApplicableTag | None | Specify array of tags to use as a filter. If cmdlet has `applicable` in the yaml metadata | -| MaxAboutWidth | 80 | Specifies the maximimum line length when generating "about" help text files. | -| ErrorLogFile | None | The path where this cmdlet will save formatted results log file | -| ShowProgress | False | Display progress bars under parsing existing markdown files | - -#### New-ExternalHelpCab - -| ParamName | DefaultValue | Description | -| -------------------- | ------------ | ------------------------------------------------------------------------------------------- | -| CabFilesFolder | None | Specifies the folder that contains the help content that this cmdlet packages into a .cab | -| LandingPagePath | None | Specifies the full path of the Module Markdown file that contains all the metadata required | -| OutputFolder | None | Specifies the location of the .cab file and helpinfo.xml file that this cmdlet creates | -| IncrementHelpVersion | False | Automatically increment the help version in the module markdown file | - -#### New-MarkdownAboutHelp - -| ParamName | DefaultValue | Description | -| ------------ | ------------ | ------------------------------------------ | -| AboutName | None | The name of the about topic | -| OutputFolder | None | The directory to create the about topic in | - -#### New-MarkdownHelp - -| ParamName | DefaultValue | Description | -| ---------------------- | ---------------- | --------------------------------------------------------------------------------------- | -| Command | None | Specifies the name of a command in your current session. This can be any command | -| Encoding | UTF8 without BOM | Specifies the character encoding for your markdown help files | -| Force | False | Indicates that this cmdlet overwrites existing files that have the same names | -| FwLink | None | Specifies the forward link for the module page. This value is required for .cab | -| HelpVersion | None | Specifies the version of your help. This value is required for .cab file creation | -| Locale | None | Specifies the locale of your help. This value is required for .cab file creation | -| MamlFile | None | Specifies an array of paths path of MAML .xml help files | -| Metadata | None | Specifies metadata that this cmdlet includes in the help markdown files as a hash table | -| Module | None | Specifies an array of names of modules for which this cmdlet creates help in markdown | -| ModuleGuid | None | Specifies the GUID of the module of your help. This value is required for .cab file | -| ModuleName | None | Specifies the name of the module of your help. This value is required for .cab file | -| NoMetadata | False | Indicates that this cmdlet does not write any metadata in the generated markdown | -| OnlineVersionUrl | None | Specifies the URL where the updatable help function downloads updated help | -| OutputFolder | None | Specifies the path of the folder where this cmdlet creates the markdown help files | -| WithModulePage | False | Indicates that this cmdlet creates a module page in the output folder | -| ConvertNotesToList | False | Indicates that this cmldet formats multiple paragraph items in the NOTES section | -| ConvertDoubleDashLists | False | Indicates that this cmldet converts double-hyphen list bullets into single-hyphen | -| AlphabeticParamsOrder | False | Order parameters alphabetically by name in PARAMETERS section. There are 5 exceptions | -| UseFullTypeName | False | Indicates that the target document will use a full type name instead of a short name | -| Session | None | Provides support for remote commands. Pass the session that you used to create | -| ModulePagePath | None | When WithModule parameter is used by default it puts .md file in same location as all | -| ExcludeDontShow | False | Exclude the parameters marked with `DontShow` in the parameter attribute from the help | - -#### New-YamlHelp - -| ParamName | DefaultValue | Description | -| ------------ | ------------ | --------------------------------------------------------------------------------------------------- | -| Encoding | None | Specifies the character encoding for your external help file. Specify a System.Text.Encoding object | -| Force | False | Indicates that this cmdlet overwrites an existing file that has the same name | -| Path | None | Specifies an array of paths of markdown files or folders | -| OutputFolder | None | Specifies the folder to create the YAML files | - -#### Update-MarkdownHelp - -| ParamName | DefaultValue | Description | -| --------------------- | ---------------- | ------------------------------------------------------------------------------------ | -| Encoding | UTF8 without BOM | Specifies the character encoding for your markdown help files | -| LogAppend | False | Indicates that this cmdlet appends information to the log instead overwriting it | -| LogPath | None | Specifies a file path for log information. The cmdlet writes the VERBOSE stream | -| Path | None | Specifies an array of paths of markdown files and folders to update | -| AlphabeticParamsOrder | False | Order parameters alphabetically by name in PARAMETERS section | -| UseFullTypeName | False | Indicates that the target document will use a full type name instead of a short name | -| Session | None | Provides support for remote commands. Pass the session that you used to create | -| UpdateInputOutput | False | Refreshes the Input and Output section to reflect the current state of the cmdlet | -| Force | False | Remove help files that no longer exists within sessions | -| ExcludeDontShow | False | Exclude the parameters marked with `DontShow` in the parameter attribute | - -#### Update-MarkdownHelpModule - -| ParamName | DefaultValue | Description | -| --------------------- | ---------------- | -------------------------------------------------------------------------------------- | -| Encoding | UTF8 without BOM | Specifies the character encoding for your markdown help files | -| LogAppend | False | Indicates that this cmdlet appends information to the log instead overwriting | -| LogPath | None | Specifies a file path for log information. The cmdlet writes the VERBOSE stream | -| Path | None | Specifies an array of paths of markdown folders to update. The folder must contain | -| RefreshModulePage | False | Update module page when updating the help module | -| AlphabeticParamsOrder | False | Order parameters alphabetically by name in PARAMETERS section | -| Session | None | Provides support for remote commands. Pass the session that you used to create | -| UseFullTypeName | False | Indicates that the target document will use a full type name instead of a short name | -| UpdateInputOutput | False | Refreshes the Input and Output sections to reflect the current state of the cmdlet | -| ModulePagePath | None | When -RefreshModulePage is used by default it puts .md file in same location | -| Force | False | Remove help files that no longer exists within sessions | -| ExcludeDontShow | False | Exclude the parameters marked with `DontShow` in the parameter attribute from the help | - -## Cmdlet Feature requests - -1. I was wondering if we should default to zips instead, one package for both platforms. Cabs as - legacy for < 5.1 content. We can fix PS 7.2 to look for zip first and fallback to cab. Add as - question in spec — This should be a switch - cab, zip or both. - -1. Need to know about Merge-MarkdownHelp which uses `applicable:` yaml syntax for version. - `applicable:` should be mentioned in the schema. — this creates tags…for linux/windows - parameters. Exchange uses the `applicable:` feature heavily. Need to maintain support for them. - -1. Need way to increment the help version number of the CAB files - - - Could be automatic in every build? - - Could be scheduled? - - Could be a workflow step (scripted) done by the author - - Need to figure out limits of version number fields - - Need rules for when to increment major, minor, subminor, etc. (Semvar?) - -### List of things that break with PS5.1 or Exchange - -TODO diff --git a/docs/developer/Microsoft.PowerShell.PlatyPS/specs/platyps_2.0_update.md b/docs/developer/Microsoft.PowerShell.PlatyPS/specs/platyps_2.0_update.md deleted file mode 100644 index 98ff28d3..00000000 --- a/docs/developer/Microsoft.PowerShell.PlatyPS/specs/platyps_2.0_update.md +++ /dev/null @@ -1,289 +0,0 @@ ---- -title: PlatyPS 2.0 specification -ms.date: 03/09/2023 ---- - -# PlatyPS 2.0 Update - -PlatyPS provides module owners with the ability to write PowerShell External Help in MarkDown. -PlatyPS generates downloadable and updatable help. - -## For this update - -PlatyPS expects Markdown to be authored in a particular way. We have defined a schema to determine -how parameters are described, where scripts examples are shown, and so on. The schema closely -resembles the existing output format of the `Get-Help` cmdlet in PowerShell. One of the primary -goals of this update is to improve the schema. The goal of 2.0.0 release is to maintain -compatibility while fixing the longstanding issues. - -This update includes the following goals: - -Priorities - -- Fix schema so that it contains all the Help Data we need while maintaining as much - compatibility as possible with PS 5.1 and Exchange -- Switch markdown engine to markdig -- Fix OPS rendering problems (requires specific changes in PlatyPS and OPS) - -After the initial release, we should look at new features and consider whether we fork the tool to a -new no-legacy feature set or try to maintain compatibility going forward (ala PowerShellGet 3.0). - -## Motivation - -PowerShell external help files have been authored by hand or using complex tool chains and rendered -as MAML XML for use as console help. MAML is cumbersome to edit by hand, and common tools and -editors don't support it for complex scenarios like they do with Markdown. PlatyPS is provided as a -solution for allow documenting PowerShell help in any editor or tool that supports Markdown. - -An additional challenge PlatyPS tackles, is to handle PowerShell documentation for complex scenarios -(e.g. very large, closed source, and/or C#/binary modules) where it may be desirable to have -documentation abstracted away from the codebase. PlatyPS does not need source access to generate -documentation. - -Markdown is designed to be human-readable, without rendering. This makes writing and editing easy -and efficient. Many editors support it (Visual Studio Code, Sublime Text, etc), and many tools and -collaboration platforms (GitHub, Visual Studio Online) render the Markdown nicely. - -## Release plan - -- Proposed Preview - - TODO - -## Goals/Non-Goals - - Goals: - -- Update the Help file schema -- Update the About_ schema -- Update the cmdlet parameters to remove/add improvements -- TODO - -Non-goals: - -- TODO - -## Specification - -The proposal is to update the functionality and schema of PlayPS to improve the module owners -experience building and updating Help. - -### Schema for cmdlet reference - -The following sections outline schema changes for the Help file. - -| Heading | Level | Required? | Count | Description | -| ------------------ | ----- | --------- | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Title | H1 | Y | 1 | - No changes | -| Synopsis | H2 | Y | 1 | - No changes | -| Aliases | H2 | Y | 1 | - New header to support documentation for cmdlet aliases | -| Syntax | H2 | Y | 1 | - No changes | -| Parameter Set Name | H3 | Y | 1-N | - Parameter Sets - should be sorted starting with Default, then by Alpha
- Parameters (in syntax block) - Should be sorted Positional, Required, then by Alpha | -| Description | H2 | Y | 1 | - Allow any content type
- No Headers H2, H3, H4 | -| Examples | H2 | Y | 1 | - No changes | -| Example | H3 | Y | 1-N | - Should require one code block at minimum per example
- Should not be restricted on elements or size | -| Parameters | H2 | Y | 1 | - Parameters Should be sorted Alpha. Currently PlatyPS has a switch to force Alpha versus enumerated. The default is off, please change to On. | -| Parameter | H3 | Y | 1-N | - Yaml block should include:
- Parameter Set Name
- AcceptedValues - Should display enumerated values of parameter (like ValidateSet)
- ConfirmImpact - Impact severity should be reflected and displayed to inform defaults for -Confirm | -| Common Parameters | H3 | Y | 1 | - Change the fwlink to remove local and version | -| Inputs | H2 | Y | 1 | - Add cross reference link to the API reference for the input/output object type
- [xref link docs][06] | -| Input type | H3 | N | 0-N | | -| Outputs | H2 | Y | 1 | - Add cross reference link to the API reference for the input/output object type
- [xref link docs][06] | -| Output type | H3 | N | 0-N | | -| Notes | H2 | N | 1 | Mandatory for schema but not rendered by OPS if empty | -| Related links | H3 | Y | 1 | - Link list should use bullets
- PlatyPS needs to support bullets
- Should support Text (prose), not just links | - -#### Updated YAML structure for parameters - -The following example shows the markdown for the Yaml metadata of a parameter. The Yaml block -contains new metadata items. - -~~~markdown -```yaml -Type: System.Management.Automation.ScopedItemOptions -Parameter Sets: (All) -Aliases: -Required: False -Position: Named -Default value: None -Accept pipeline input: ByValue (False), ByName (False) -Accept wildcard characters: False -Dynamic: True -Providers: Alias, Function -Values from remaining args: False -Do not show: False -Is credential: False -Is obsolete: False -Release status: Feature Preview -``` -~~~ - -Notes - -- Values for most items should be obtained by reflection. -- Provider information will have to be tested individually based on the currently loaded providers. -- The `Default value` should be obtained by reflection, if possible. - - The default value for **SwitchParameter** types should be `False`. -- If possible, the `Parameter sets` and `Providers` values should be simplified to show `(All)` when - the value is the same for all parameter sets or providers. - -New metadata - -- `Dynamic` - - Type: boolean - - Obtained by reflection of parameter attributes - - Required -- `Providers` - - Type: string containing one or more provider names (comma-separated) - - Optional - expected when `Dynamic` is true -- `Values from remaining args` - - Type: boolean - - Obtained by reflection of parameter attributes - - Required -- `Do not show` - - Type: boolean - - Obtained by reflection of parameter attributes - - Required -- `Is credential` - - Type: boolean - - Obtained by reflection of parameter attributes - - Required -- `Is obsolete` - - Type: boolean - - Obtained by reflection of parameter attributes - - Required -- `Release status` - - Type: string representation of one enum value from: - - 'Preview' - typically not used for parameters - - 'Feature Preview' - typically not used for parameters - - 'Experimental' - used for parameters that are enabled by a PowerShell experimental feature - - 'Deprecated' - used for cmdlet that will be unsupported after a certain date are removed in a - future release - - Null value - indicates the parameter is GA (currently supported) - - Optional - the value can be null or the key-value pair omitted - -The OPS build pipeline should validate that the values match the type. `Release status` should only -be rendered on the page if the key has a value (not null). - -### Schema updates for cmdlet frontmatter - -#### Cmdlet alias metadata - -Have a way to document aliases for the cmdlet. Today we only document aliases for parameters. This -is difficult to discover, so don't need `*-MarkdownHelp` cmdlets to create it but the schema needs -to support it. The author can add the information to the YAML frontmatter. For example: - -```yaml -aliases: [dir, gci, ls] -``` - -Add new H2 for documenting aliases. - -```markdown -## ALIASES - -PowerShell includes the following aliases for `Get-ChildItem`: - -- All platforms: `dir`, `gci` -- Windows: `ls` -``` - -See [alias-prototype][02] for a more complete example. - -> [!NOTE] -> The `aliases` metadata is optional. The information will be added by the documentation author. The -> ALIASES H2 section is optional and will be added by the documentation author as necessary. The -> reference pipeline shouldn't try to validate this content or metadata values. The reference -> pipeline should add all aliases to the `displayname` property of the Yaml TOC entry for the -> cmdlet. For more information about the `displayname` property, see the [TOC docs][07]. - -See [Issue #585][04]. - -#### Cmdlet platform availability - -The purpose of this is to represent the availability of the cmdlet for a platform (win/mac/linux). -Could be one or more. PlatyPS could default to Windows when creating the markdown. The value should -be edited by the author to ensure accuracy. - -```yaml -- platforms: [win, macOS, linux] -``` - -- `platforms` - - Type: string array containing one or more platform names (win, macOS, linux) - - Required - -The reference build pipeline should enforce the requirement but doesn't need to use the values - -#### Cmdlet release status metadata - -The purpose of this metadata is to represent the release status of the cmdlet. The value isn't -required if the cmdlet is GA. This metadata will be added by the author as necessary. - -PlatyPS should create the metadata as placeholders in the frontmatter. The author should delete the -keys or update the values as appropriate. - -```yaml -release: - status : Preview, Feature Preview, Experimental, Deprecated - message : Text of a banner message. -``` - -- `release` - - Type: string representation of one enum value from: - - 'Preview', 'Feature Preview', 'Experimental', 'Deprecated' - - Optional -- `status` - - Type: string representation of one enum value from: - - 'Preview' - used for cmdlets from preview modules where the version is 0.x.y with no - Prerelease label - - 'Feature Preview' - used for cmdlets from feature preview modules where the version is 1.x.y - or higher and has a Prerelease label - - 'Experimental' - used for cmdlets that are enabled by a PowerShell experimental feature - - 'Deprecated' - used for cmdlet that will be unsupported after a certain date are removed in a - future release - - Required -- `message` - - Type: string - text of an alert message to be displayed in the documentation - - The message should be a single sentence or short paragraph. Include end of support dates if - applicable. - - Required - -The reference build pipeline should do the following: - -- Use the `status` to select the badge displayed for the status. -- Use the `message` to render an alert box on the page containing the message -- Validate that the values match the types. - -Matt Trilby-Bassett has some [Figma designs][08] showing the badge and alert box. - -### Schema for Module file frontmatter - -The `Module.md` file is the landing page for a module and is used during conversion to MAML. The -frontmatter for this file will also include the `release` metadata for non-GA modules. - -See the [release status metadata][01] described above. - -The reference build pipeline will use: - -- the `status` to select the badge displayed for the status. -- the `message` to render an alert box on the page containing the message - -### PlatyPS formatting changes - -- General - - Would like PlatyPS to add a line break after each Markdown block - - Example - Headers, Code blocks, Lists - - Bug: `Get-Help`: Requires that the first line of text be immediately following Synopsis header - -## Issues for this milestone - -[2.0-consider][03] - - -[01]: #cmdlet-release-status-metadata -[02]: alias-prototype.md -[03]: https://github.com/PowerShell/platyPS/issues?q=is%3Aopen+is%3Aissue+milestone%3A2.0-consider -[04]: https://github.com/PowerShell/platyPS/issues/585 -[05]: https://github.com/PowerShell/PowerShell/issues/9208 -[06]: https://review.docs.microsoft.com/en-us/help/contribute/links-how-to?branch=master#xref-cross-reference-links -[07]: https://review.learn.microsoft.com/en-us/help/platform/navigation-toc-overview?branch=main#yaml-toc-format -[08]: https://www.figma.com/file/EP3wMMct92SqHwvWcorb9O/%5BDiscovery%5D-Reference-Development-Status-Information?node-id=897%3A3314&t=zy1ygL7Gh5ChSyh1-0 diff --git a/docs/developer/platyPS/CONTRIBUTING.md b/docs/developer/platyPS/CONTRIBUTING.md deleted file mode 100644 index c0a901cd..00000000 --- a/docs/developer/platyPS/CONTRIBUTING.md +++ /dev/null @@ -1,138 +0,0 @@ -# Contributing to platyPS - -## Get the code - -``` -git clone https://github.com/PowerShell/platyPS -``` - -## Understand code layout - -There are two parts: - -- `Markdown.MAML.dll`, a .NET library written in C#. It does the heavy lifting, like parsing - Markdown, transforming it into XML, and so on. You can open `.\Markdown.MAML.sln` in Visual Studio - on any platform. -- A PowerShell module in `.\src\platyPS`. This module provides the user CLI. - -## Build - -To build the whole project, use the `build.ps1` helper script. It depends on the [dotnet cli][01] -build tool. - -On Windows you would also need to [install full dotnet framework][02] if it's not installed already. - -```powershell -.\build.ps1 -``` - -As part of the build, platyPS generates help for itself. The output of the build is placed in -`out\Microsoft.PowerShell.PlatyPS`. - -`build.ps1` also imports the module from `out\platyPS` and generates help itself. - -> [!NOTE] -> If you changed C# code, `build.ps1` will try to overwrite a DLL in use. You will then need to -> re-open your PowerShell session. If you know a better workflow, please suggest it in the Issues. - -## Tests - -Each part of the project has a test set: - -- The C# part has xUnit tests. You can run them from Visual Studio or from command line with - `dotnet test ./test/Markdown.MAML.Test`. -- The PowerShell part has [Pester][03] tests. You can run them with `Invoke-Pester`. - -> [!NOTE] -> Pester tests always force-import the module from the output location of `.\build.ps1`. - -## Schema - -If you have ideas or concerns about the Markdown schema, feel free to open a GitHub Issue to discuss -it. - -## Repo structure - -- **src\platyPS** - sources to create the final PowerShell module. -- **src\Markdown.MAML, Markdown.MAML.sln** - source code for C# Markdown to MAML converter. -- **[platyPS.schema.md][04]** - description of Markdown that platyPS expects. - -## Data transformations - -Data transformations are the core of platyPS. A user has content in some form and she wants to -transform it into another form. E.g. transform existing module help (in MAML) to Markdown and use it -in the future to generate the external help (MAML) and static HTML for online references. - -platyPS provides APIs in the form of cmdlets for end-user scenarios. These scenarios are assembled -from simple transformations. This chart describes these simple transformations: - -``` - +----------+ - | | - | HTML | - | | - +------^---+ - | - +------+------------+ +-----------------+ - | | | Markdown Model | - | Markdown file +-----------> | - | | +-+---------------+ - | | | - +---------------^---+ | - | | - | | - | | - +--+-----------------v--+ - | MAML Model | - | (= Generic Help model)| - | | - +--+-------------------^+ - | | - | | - | | -+----------------v-----+ ++--------------------------+ -| MAML XML file | | Help Object in PowerShell | -| (External help file) +------------> (+ Get-Command object) | -+----------------------+ +---------------------------+ -``` - -### Example `New-MarkdownHelp` - -A user creates a platyPS Markdown for the first time with `New-MarkdownHelp`: - -```powershell -New-MarkdownHelp -Command New-MyCommandHelp -``` - -Under the hood, the following tranformations happen: - -``` -[MAML XML file] --> [Help Object + Get-Command object] --> [MAML Model] --> [Markdown file] -``` - -# Making a new release - -1. Make sure that `CHANGELOG.md` is up-to-date, move section from `UNRELEASED` to new section - ``. -1. Make sure platyPS help itself (content in .\docs folder) is up to date. - `Update-MarkdownHelp -Path .\docs` should result in no changes. -1. Do not change the version in platyps.psd1. Git tag will update this version for release. -1. From master, tag the release. -1. Push tag to GitHub. -1. Find the corresponding build on AppVeyor. -1. Download ZIP archive with the module from Appveyor's Artifacts tab. -1. Unblock the ZIP archive (`Unblock-File foo.zip`), and copy the ZIP's contents to - `$env:PSMODULEPATH` so it's available to `Publish-Module`. -1. Publish the module to the Gallery: - `Publish-Module -RequiredVersion -Verbose -NuGetApiKey $apiKey`. -1. Check that https://www.powershellgallery.com/packages/platyPS/ updated. -1. Publish a new github release from https://github.com/PowerShell/platyPS/releases to move "Latest - release" label to the new tag. - -Congratulations! You just made a release. - - -[01]: https://docs.microsoft.com/en-us/dotnet/core/tools/ -[02]: https://docs.microsoft.com/en-us/dotnet/framework/install/guide-for-developers -[03]: https://github.com/pester/Pester -[04]: platyPS.schema.md diff --git a/docs/developer/platyPS/platyPS.schema.md b/docs/platyPS.schema.md similarity index 100% rename from docs/developer/platyPS/platyPS.schema.md rename to docs/platyPS.schema.md diff --git a/docs/cmdlet-reference/platyPS/Get-HelpPreview.md b/docs/platyPS/Get-HelpPreview.md similarity index 100% rename from docs/cmdlet-reference/platyPS/Get-HelpPreview.md rename to docs/platyPS/Get-HelpPreview.md diff --git a/docs/cmdlet-reference/platyPS/Get-MarkdownMetadata.md b/docs/platyPS/Get-MarkdownMetadata.md similarity index 100% rename from docs/cmdlet-reference/platyPS/Get-MarkdownMetadata.md rename to docs/platyPS/Get-MarkdownMetadata.md diff --git a/docs/cmdlet-reference/platyPS/Merge-MarkdownHelp.md b/docs/platyPS/Merge-MarkdownHelp.md similarity index 100% rename from docs/cmdlet-reference/platyPS/Merge-MarkdownHelp.md rename to docs/platyPS/Merge-MarkdownHelp.md diff --git a/docs/cmdlet-reference/platyPS/New-ExternalHelp.md b/docs/platyPS/New-ExternalHelp.md similarity index 100% rename from docs/cmdlet-reference/platyPS/New-ExternalHelp.md rename to docs/platyPS/New-ExternalHelp.md diff --git a/docs/cmdlet-reference/platyPS/New-ExternalHelpCab.md b/docs/platyPS/New-ExternalHelpCab.md similarity index 100% rename from docs/cmdlet-reference/platyPS/New-ExternalHelpCab.md rename to docs/platyPS/New-ExternalHelpCab.md diff --git a/docs/cmdlet-reference/platyPS/New-MarkdownAboutHelp.md b/docs/platyPS/New-MarkdownAboutHelp.md similarity index 100% rename from docs/cmdlet-reference/platyPS/New-MarkdownAboutHelp.md rename to docs/platyPS/New-MarkdownAboutHelp.md diff --git a/docs/cmdlet-reference/platyPS/New-MarkdownHelp.md b/docs/platyPS/New-MarkdownHelp.md similarity index 100% rename from docs/cmdlet-reference/platyPS/New-MarkdownHelp.md rename to docs/platyPS/New-MarkdownHelp.md diff --git a/docs/cmdlet-reference/platyPS/New-YamlHelp.md b/docs/platyPS/New-YamlHelp.md similarity index 100% rename from docs/cmdlet-reference/platyPS/New-YamlHelp.md rename to docs/platyPS/New-YamlHelp.md diff --git a/docs/cmdlet-reference/platyPS/Update-MarkdownHelp.md b/docs/platyPS/Update-MarkdownHelp.md similarity index 100% rename from docs/cmdlet-reference/platyPS/Update-MarkdownHelp.md rename to docs/platyPS/Update-MarkdownHelp.md diff --git a/docs/cmdlet-reference/platyPS/Update-MarkdownHelpModule.md b/docs/platyPS/Update-MarkdownHelpModule.md similarity index 100% rename from docs/cmdlet-reference/platyPS/Update-MarkdownHelpModule.md rename to docs/platyPS/Update-MarkdownHelpModule.md diff --git a/docs/cmdlet-reference/platyPS/about_platyPS.md b/docs/platyPS/about_platyPS.md similarity index 100% rename from docs/cmdlet-reference/platyPS/about_platyPS.md rename to docs/platyPS/about_platyPS.md diff --git a/docs/developer/platyPS/presentation/css/impress-demo.css b/docs/presentation/css/impress-demo.css similarity index 100% rename from docs/developer/platyPS/presentation/css/impress-demo.css rename to docs/presentation/css/impress-demo.css diff --git a/docs/developer/platyPS/presentation/images/FFFUUU.png b/docs/presentation/images/FFFUUU.png similarity index 100% rename from docs/developer/platyPS/presentation/images/FFFUUU.png rename to docs/presentation/images/FFFUUU.png diff --git a/docs/developer/platyPS/presentation/images/azure-maml.png b/docs/presentation/images/azure-maml.png similarity index 100% rename from docs/developer/platyPS/presentation/images/azure-maml.png rename to docs/presentation/images/azure-maml.png diff --git a/docs/developer/platyPS/presentation/images/get-help.png b/docs/presentation/images/get-help.png similarity index 100% rename from docs/developer/platyPS/presentation/images/get-help.png rename to docs/presentation/images/get-help.png diff --git a/docs/developer/platyPS/presentation/images/markdown-github.png b/docs/presentation/images/markdown-github.png similarity index 100% rename from docs/developer/platyPS/presentation/images/markdown-github.png rename to docs/presentation/images/markdown-github.png diff --git a/docs/developer/platyPS/presentation/images/markdown.png b/docs/presentation/images/markdown.png similarity index 100% rename from docs/developer/platyPS/presentation/images/markdown.png rename to docs/presentation/images/markdown.png diff --git a/docs/developer/platyPS/presentation/images/pscmdlethelpeditor.png b/docs/presentation/images/pscmdlethelpeditor.png similarity index 100% rename from docs/developer/platyPS/presentation/images/pscmdlethelpeditor.png rename to docs/presentation/images/pscmdlethelpeditor.png diff --git a/docs/developer/platyPS/presentation/images/psreadline-maml.png b/docs/presentation/images/psreadline-maml.png similarity index 100% rename from docs/developer/platyPS/presentation/images/psreadline-maml.png rename to docs/presentation/images/psreadline-maml.png diff --git a/docs/developer/platyPS/presentation/index.html b/docs/presentation/index.html similarity index 100% rename from docs/developer/platyPS/presentation/index.html rename to docs/presentation/index.html diff --git a/docs/developer/platyPS/presentation/js/impress.js b/docs/presentation/js/impress.js similarity index 100% rename from docs/developer/platyPS/presentation/js/impress.js rename to docs/presentation/js/impress.js From e32c510108a455aae6018dccebe9b5c9e8ad4e9c Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Wed, 30 Jul 2025 08:08:15 -0500 Subject: [PATCH 27/27] Update v0.14 schema docs and add code design doc --- docs/CODE-LAYOUT.md | 138 +++++++++++++++++++++ docs/platyPS.schema.md | 265 +++++++++++++++++++++-------------------- 2 files changed, 275 insertions(+), 128 deletions(-) create mode 100644 docs/CODE-LAYOUT.md diff --git a/docs/CODE-LAYOUT.md b/docs/CODE-LAYOUT.md new file mode 100644 index 00000000..c0a901cd --- /dev/null +++ b/docs/CODE-LAYOUT.md @@ -0,0 +1,138 @@ +# Contributing to platyPS + +## Get the code + +``` +git clone https://github.com/PowerShell/platyPS +``` + +## Understand code layout + +There are two parts: + +- `Markdown.MAML.dll`, a .NET library written in C#. It does the heavy lifting, like parsing + Markdown, transforming it into XML, and so on. You can open `.\Markdown.MAML.sln` in Visual Studio + on any platform. +- A PowerShell module in `.\src\platyPS`. This module provides the user CLI. + +## Build + +To build the whole project, use the `build.ps1` helper script. It depends on the [dotnet cli][01] +build tool. + +On Windows you would also need to [install full dotnet framework][02] if it's not installed already. + +```powershell +.\build.ps1 +``` + +As part of the build, platyPS generates help for itself. The output of the build is placed in +`out\Microsoft.PowerShell.PlatyPS`. + +`build.ps1` also imports the module from `out\platyPS` and generates help itself. + +> [!NOTE] +> If you changed C# code, `build.ps1` will try to overwrite a DLL in use. You will then need to +> re-open your PowerShell session. If you know a better workflow, please suggest it in the Issues. + +## Tests + +Each part of the project has a test set: + +- The C# part has xUnit tests. You can run them from Visual Studio or from command line with + `dotnet test ./test/Markdown.MAML.Test`. +- The PowerShell part has [Pester][03] tests. You can run them with `Invoke-Pester`. + +> [!NOTE] +> Pester tests always force-import the module from the output location of `.\build.ps1`. + +## Schema + +If you have ideas or concerns about the Markdown schema, feel free to open a GitHub Issue to discuss +it. + +## Repo structure + +- **src\platyPS** - sources to create the final PowerShell module. +- **src\Markdown.MAML, Markdown.MAML.sln** - source code for C# Markdown to MAML converter. +- **[platyPS.schema.md][04]** - description of Markdown that platyPS expects. + +## Data transformations + +Data transformations are the core of platyPS. A user has content in some form and she wants to +transform it into another form. E.g. transform existing module help (in MAML) to Markdown and use it +in the future to generate the external help (MAML) and static HTML for online references. + +platyPS provides APIs in the form of cmdlets for end-user scenarios. These scenarios are assembled +from simple transformations. This chart describes these simple transformations: + +``` + +----------+ + | | + | HTML | + | | + +------^---+ + | + +------+------------+ +-----------------+ + | | | Markdown Model | + | Markdown file +-----------> | + | | +-+---------------+ + | | | + +---------------^---+ | + | | + | | + | | + +--+-----------------v--+ + | MAML Model | + | (= Generic Help model)| + | | + +--+-------------------^+ + | | + | | + | | ++----------------v-----+ ++--------------------------+ +| MAML XML file | | Help Object in PowerShell | +| (External help file) +------------> (+ Get-Command object) | ++----------------------+ +---------------------------+ +``` + +### Example `New-MarkdownHelp` + +A user creates a platyPS Markdown for the first time with `New-MarkdownHelp`: + +```powershell +New-MarkdownHelp -Command New-MyCommandHelp +``` + +Under the hood, the following tranformations happen: + +``` +[MAML XML file] --> [Help Object + Get-Command object] --> [MAML Model] --> [Markdown file] +``` + +# Making a new release + +1. Make sure that `CHANGELOG.md` is up-to-date, move section from `UNRELEASED` to new section + ``. +1. Make sure platyPS help itself (content in .\docs folder) is up to date. + `Update-MarkdownHelp -Path .\docs` should result in no changes. +1. Do not change the version in platyps.psd1. Git tag will update this version for release. +1. From master, tag the release. +1. Push tag to GitHub. +1. Find the corresponding build on AppVeyor. +1. Download ZIP archive with the module from Appveyor's Artifacts tab. +1. Unblock the ZIP archive (`Unblock-File foo.zip`), and copy the ZIP's contents to + `$env:PSMODULEPATH` so it's available to `Publish-Module`. +1. Publish the module to the Gallery: + `Publish-Module -RequiredVersion -Verbose -NuGetApiKey $apiKey`. +1. Check that https://www.powershellgallery.com/packages/platyPS/ updated. +1. Publish a new github release from https://github.com/PowerShell/platyPS/releases to move "Latest + release" label to the new tag. + +Congratulations! You just made a release. + + +[01]: https://docs.microsoft.com/en-us/dotnet/core/tools/ +[02]: https://docs.microsoft.com/en-us/dotnet/framework/install/guide-for-developers +[03]: https://github.com/pester/Pester +[04]: platyPS.schema.md diff --git a/docs/platyPS.schema.md b/docs/platyPS.schema.md index 25b8d7f5..9dd3878a 100644 --- a/docs/platyPS.schema.md +++ b/docs/platyPS.schema.md @@ -5,98 +5,151 @@ It closely resembles output of `Get-Help`. ## Legend -* `{string}` - single-line string value -* `{{text}}` - multi-line text -* `//` - line comment in schema -* tabs show the scopes of `// for` statements; they should not be included in the Markdown output. +- `{string}` - single-line string value +- `{{text}}` - multi-line text +- `//` - line comment in schema +- tabs show the scopes of `// for` statements; they should not be included in the Markdown output. ### Version 2.0.0 - - // Every cmdlet help placed in it's own `Command-Name.md` file in one folder. - // We sometimes reference to this folder as "HelpModule". - - // Top-level metadata. You can put your own "key: value" statements there - // unknown values would be ignored by platyPS - // You can query this data from markdown file with `Get-MarkdownMetadata` - // - // Keys that have meaning for platyPS have separate entries - --- - schema: 2.0.0 - external help file: {file name for `New-ExternalHelp`}.xml - online version: {url for `Get-Help -Online`} - applicable: {comma-separated list of tags where this cmdlet exists} // if omitted then applicable for any tag - {{ User-specific key-value pairs }} - --- +``` +// Every cmdlet help placed in it's own `Command-Name.md` file in one folder. +// We sometimes reference to this folder as "HelpModule". + +// Top-level metadata. You can put your own "key: value" statements there +// unknown values would be ignored by platyPS +// You can query this data from markdown file with `Get-MarkdownMetadata` +// +// Keys that have meaning for platyPS have separate entries +--- +schema: 2.0.0 +external help file: {file name for `New-ExternalHelp`}.xml +online version: {url for `Get-Help -Online`} +applicable: {comma-separated list of tags where this cmdlet exists} // if omitted then applicable for any tag +{{ User-specific key-value pairs }} +--- + +# {Command name} + +// following level-2 headers sections can go in any order +// here is the recommended order + +## SYNOPSIS +{{Synopsis text}} + +## SYNTAX +// for each parameter set + ### {Parameter Set Name, if default parameter set, followed by "(Default)"} + // i.e.: FromPath (Default) + // This syntax would be ignored during maml generation. + // syntax would be generated from parameters metadata + ``` + {{Output of Get-Command -Syntax}} + ``` + +## DESCRIPTION +{{Description text}} + +## EXAMPLES +// for every example + ### {Example Name} + + {{Example introduction text}} + + // one or more times, codesnippet + // it's useful to put the ```powershell code + // before the plain text command execution output + ```{Syntax language, i.e. PowerShell or nothing for plain text} + {{Example body}} + ``` + + {{Example remarks}} // not a mandatory, i.e. TechNet articles don't use remarks + +## PARAMETERS + +// for every parameter + // default value is non-mandatory + ### -{Parameter name} + {{Parameter description text. It can also include codesnippets, but they could not be ```yaml}} + + // parameter metadata + // for every unique parameter metadata set + // Note: two Parameter Sets can have the same parameter as mandatory and non-mandatory + // then we put them in two yaml snippets. + // If they have the same metadata, we put them in one yaml snippet. + + ```yaml // this gives us key/value highlighting + Type: {Parameter type} // can be ommitted, then default assumed + Parameter sets: {comma-separated list of names, i.e. "SetName1, SetName2" or "(All)" + for all parameter sets} + Aliases: {comma-separated list of aliases, i.e. EA, ERR} // if ommitted => default + Accepted values: {ValidateSet, comma-separated list of valid values, i.e. Foo, Bar} + // if ommitted => everything is accepted + Applicable: {comma-separated list of tags where this cmdlet exists} + // if omitted then applicable for any tag + // break line to improve readability and separate metadata block + + Required: {true | false} + Position: {1..n} | named + Default value: {None | False (for switch parameters) | the actual default value} + Accept pipeline input: {false | true (ByValue, ByPropertyName)} + Accept wildcard characters: {true | false} + ``` + + // if supports workflow parameters + ### + {{ Workflow common parameters text, would be ignored during maml generation }} + + // if supports common parameters + ### + {{ Common parameters text, would be ignored during maml generation }} + +## INPUTS // for every input type +### {Input type} +{{Description text}} + +## OUTPUTS // for every output type + +### {Output type} +{{Description text}} + +## RELATED LINKS + +// for every link +[{link name}]({link url}) +``` + +### Version 1.0.0 (Deprecated) + +v0.7.6 is the last platyPS version that supports it. + +``` +// for every command: # {Command name} // following level-2 headers sections can go in any order // here is the recommended order - + ## SYNOPSIS {{Synopsis text}} - ## SYNTAX - // for each parameter set - ### {Parameter Set Name, if default parameter set, followed by "(Default)"} - // i.e.: FromPath (Default) - // This syntax would be ignored during maml generation. - // syntax would be generated from parameters metadata - ``` - {{Output of Get-Command -Syntax}} - ``` - ## DESCRIPTION {{Description text}} - ## EXAMPLES - // for every example - ### {Example Name} - - {{Example introduction text}} - - // one or more times, codesnippet - // it's useful to put the ```powershell code - // before the plain text command exectution output - ```{Syntax language, i.e. PowerShell or nothing for plain text} - {{Example body}} - ``` - - {{Example remarks}} // not a mandatory, i.e. TechNet articles don't use remarks - ## PARAMETERS // for every parameter - // default value is non-mandatory - ### -{Parameter name} - {{Parameter description text. It can also include codesnippets, but they could not be ```yaml}} + // type and default value are non-mandatory + ### {Parameter name} [{Parameter type}] = {Parameter default value} // parameter metadata - // for every unique parameter metadata set - // Note: two Parameter Sets can have the same parameter as mandatory and non-mandatory - // then we put them in two yaml snippets. - // If they have the same metadata, we put them in one yaml snippet. - ```yaml // this gives us key/value highlighting - Type: {Parameter type} // can be ommitted, then default assumed - Parameter sets: {comma-separated list of names, i.e. "SetName1, SetName2" or "(All)" for all parameter sets} - Aliases: {comma-separated list of aliases, i.e. EA, ERR} // if ommitted => default - Accepted values: {ValidateSet, comma-separated list of valid values, i.e. Foo, Bar} // if ommitted => everything is accepted - Applicable: {comma-separated list of tags where this cmdlet exists} // if omitted then applicable for any tag - // break line to improve readability and separate metadata block - - Required: {true | false} - Position: {1..n} | named - Default value: {None | False (for switch parameters) | the actual default value} - Accept pipeline input: {false | true (ByValue, ByPropertyName)} - Accept wildcard characters: {true | false} - ``` - // if supports workflow parameters - ### - {{ Workflow common parameters text, would be ingored during maml generation }} - - // if supports common parameters - ### - {{ Common parameters text, would be ingored during maml generation }} + ```powershell + {{Parameter attributes as specified in param() block in PowerShell functions + i.e. [Parameter(ParameterSetName = 'ByName')] + }} + ``` + + {{Parameter description text}} ## INPUTS // for every input type @@ -108,61 +161,17 @@ It closely resembles output of `Get-Help`. ### {Output type} {{Description text}} + ## EXAMPLES + // for every example + ### {Example Name} + + ```powershell + {{Example body}} + ``` + {{Example text explanation}} + ## RELATED LINKS // for every link [{link name}]({link url}) - -### Version 1.0.0 (Deprecated) -v0.7.6 is the last platyPS version that supports it. - - // for every command: - # {Command name} - - // following level-2 headers sections can go in any order - // here is the recommended order - - ## SYNOPSIS - {{Synopsis text}} - - ## DESCRIPTION - {{Description text}} - - ## PARAMETERS - - // for every parameter - // type and default value are non-mandatory - ### {Parameter name} [{Parameter type}] = {Parameter default value} - - // parameter metadata - ```powershell - {{Parameter attributes as specified in param() block in PowerShell functions - i.e. [Parameter(ParameterSetName = 'ByName')] - }} - ``` - - {{Parameter description text}} - - ## INPUTS - // for every input type - ### {Input type} - {{Description text}} - - ## OUTPUTS - // for every output type - ### {Output type} - {{Description text}} - - ## EXAMPLES - // for every example - ### {Example Name} - - ```powershell - {{Example body}} - ``` - {{Example text explanation}} - - ## RELATED LINKS - - // for every link - [{link name}]({link url}) +```