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..089e6e40 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,11 @@ +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/CHANGELOG.md b/CHANGELOG.md index 930bbc0b..2c7d5434 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,23 +1,36 @@ -CHANGELOG -------------- +# CHANGELOG ## Not released -# 0.14.1 +## 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 +- 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 - 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/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 dbb786c1..e0f3ca2d 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://powershellgallery.com): +- 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,64 +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 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 a module page .md with summary. It will also allow you to create updatable help cab. +## Remoting -* Retrieve markdown metadata from markdown file. +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. -* Create external help xml files (MAML) from platyPS Markdown. +## Build -* Create external help file cab +For information about building from sources and contributing see [contributing guidelines][02]. -* Preview help from generated maml file. +## Code of Conduct -## Remoting +Please see our [Code of Conduct][01] before participating in this project. -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. +## Security Policy -## Build +For any security issues, please see our [Security Policy][08]. -For information about building from sources and contributing see [contributing guidelines](CONTRIBUTING.md). + +[01]: CODE_OF_CONDUCT.md +[02]: docs/developer/platyPS/CONTRIBUTING.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/ +[07]: https://www.powershellgallery.com/packages/platyPS +[08]: 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). + + 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() 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..5ce78eac --- /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: 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 new file mode 100644 index 00000000..d67b480e --- /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: 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 new file mode 100644 index 00000000..3354322e --- /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: 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 new file mode 100644 index 00000000..cd98c273 --- /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: 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 new file mode 100644 index 00000000..8c2eae73 --- /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: 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 new file mode 100644 index 00000000..8ca585d6 --- /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: 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 new file mode 100644 index 00000000..f4b0c993 --- /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: 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 new file mode 100644 index 00000000..4d33b5f7 --- /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: 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 new file mode 100644 index 00000000..42834ec9 --- /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: 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 new file mode 100644 index 00000000..14763183 --- /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: 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 new file mode 100644 index 00000000..d8d7adfb --- /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: 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 new file mode 100644 index 00000000..fa1a8f73 --- /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: 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 new file mode 100644 index 00000000..13fd61f6 --- /dev/null +++ b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Microsoft.PowerShell.PlatyPS.md @@ -0,0 +1,106 @@ +--- +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 new file mode 100644 index 00000000..1167b4a7 --- /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: 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 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 new file mode 100644 index 00000000..9d4e60f7 --- /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: 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 new file mode 100644 index 00000000..7efaec1e --- /dev/null +++ b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/New-MarkdownModuleFile.md @@ -0,0 +1,354 @@ +--- +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 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 new file mode 100644 index 00000000..1e7aa03a --- /dev/null +++ b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Test-MarkdownCommandHelp.md @@ -0,0 +1,171 @@ +--- +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 new file mode 100644 index 00000000..09e46c58 --- /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: 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 new file mode 100644 index 00000000..670c7e85 --- /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: 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 new file mode 100644 index 00000000..e5e8a8d2 --- /dev/null +++ b/docs/cmdlet-reference/Microsoft.PowerShell.PlatyPS/Update-MarkdownModuleFile.md @@ -0,0 +1,382 @@ +--- +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/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/docs/developer/Microsoft.PowerShell.PlatyPS/specs/PowerShellCmdlet.schema.json b/docs/developer/Microsoft.PowerShell.PlatyPS/specs/PowerShellCmdlet.schema.json new file mode 100644 index 00000000..8636f27e --- /dev/null +++ b/docs/developer/Microsoft.PowerShell.PlatyPS/specs/PowerShellCmdlet.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/docs/developer/Microsoft.PowerShell.PlatyPS/specs/PowershellCmdletV2.schema.json b/docs/developer/Microsoft.PowerShell.PlatyPS/specs/PowershellCmdletV2.schema.json new file mode 100644 index 00000000..2e9e70c1 --- /dev/null +++ b/docs/developer/Microsoft.PowerShell.PlatyPS/specs/PowershellCmdletV2.schema.json @@ -0,0 +1,257 @@ +{ + "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 new file mode 100644 index 00000000..2c279340 --- /dev/null +++ b/docs/developer/Microsoft.PowerShell.PlatyPS/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 diff --git a/docs/developer/Microsoft.PowerShell.PlatyPS/specs/alias-prototype.md b/docs/developer/Microsoft.PowerShell.PlatyPS/specs/alias-prototype.md new file mode 100644 index 00000000..9da66a77 --- /dev/null +++ b/docs/developer/Microsoft.PowerShell.PlatyPS/specs/alias-prototype.md @@ -0,0 +1,41 @@ +--- +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 new file mode 100644 index 00000000..6d16b18e --- /dev/null +++ b/docs/developer/Microsoft.PowerShell.PlatyPS/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/docs/developer/Microsoft.PowerShell.PlatyPS/specs/platyps_2.0_cmdlets.md b/docs/developer/Microsoft.PowerShell.PlatyPS/specs/platyps_2.0_cmdlets.md new file mode 100644 index 00000000..33aeb0d2 --- /dev/null +++ b/docs/developer/Microsoft.PowerShell.PlatyPS/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/docs/developer/Microsoft.PowerShell.PlatyPS/specs/platyps_2.0_update.md b/docs/developer/Microsoft.PowerShell.PlatyPS/specs/platyps_2.0_update.md new file mode 100644 index 00000000..98ff28d3 --- /dev/null +++ b/docs/developer/Microsoft.PowerShell.PlatyPS/specs/platyps_2.0_update.md @@ -0,0 +1,289 @@ +--- +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/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 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/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/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/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 153604d0..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' { @@ -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' { @@ -1603,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' @@ -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