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/.gitignore b/.gitignore index 1de269d1..74aeb8ea 100644 --- a/.gitignore +++ b/.gitignore @@ -9,14 +9,14 @@ *.sln.docstates # Build results -[Dd]ebug/ -[Dd]ebugPublic/ -[Rr]elease/ -x64/ -build/ -bld/ -[Bb]in/ -[Oo]bj/ +**/[Dd]ebug/ +**[Dd]ebugPublic/ +**[Rr]elease/ +**x64/ +**build/ +**bld/ +**[Bb]in/ +**[Oo]bj/ # Roslyn cache directories *.ide/ diff --git a/.travis.yml b/.travis.yml deleted file mode 100644 index c260d807..00000000 --- a/.travis.yml +++ /dev/null @@ -1,24 +0,0 @@ -# that gives us dotnet cli installed on the box -language: csharp - -dist: trusty -sudo: required - -mono: none -dotnet: 2.0.0 - -# instruction from https://github.com/PowerShell/PowerShell/blob/master/docs/installation/linux.md#ubuntu-1404 - -install: - - curl https://packages.microsoft.com/keys/microsoft.asc | sudo apt-key add - - - curl https://packages.microsoft.com/config/ubuntu/14.04/prod.list | sudo tee /etc/apt/sources.list.d/microsoft.list - - sudo apt-get update - - sudo apt-get install -y powershell=6.0.2-1.ubuntu.14.04 - -script: - - pwsh ./build.ps1 - - dotnet test ./test/Markdown.MAML.Test - - sudo pwsh -C 'Install-Module Pester -Force' - # updated help is needed for tests, run as a Job to avoid Write-Progress output - - sudo pwsh -C '(update-help &) | Wait-Job' - - pwsh -C 'Invoke-Pester -EnableExit' diff --git a/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 deleted file mode 100644 index 3f444e08..00000000 --- a/appveyor.yml +++ /dev/null @@ -1,63 +0,0 @@ -version: 0.11.0.{build} - -install: - - ps: | - Write-Host "PowerShell Version:" $PSVersionTable.PSVersion.tostring() - Install-PackageProvider -Name NuGet -MinimumVersion 2.8.5.201 -Force - Install-Module -Name Pester -RequiredVersion 4.10.1 -Force - -init: - - git config --global core.autocrlf true - -build_script: - - ps: | - $ErrorActionPreference = 'Stop' - Update-Help Microsoft.PowerShell.Core, Microsoft.PowerShell.Management, Microsoft.PowerShell.Utility -Force # we need up-to-date help content for tests - .\build.ps1 -Configuration Release - -test_script: - - dotnet test .\test\Markdown.MAML.Test - -after_test: - - ps: | - # We run Pester tests in after_test step - # we don't want to use test_script - # appveyor doesn't run after_test, if tests failed. - # - # Pester tests produce artifacts in .\out directory - $pesterTestResultsFile = ".\TestsResults.xml" - $res = Invoke-Pester -OutputFormat NUnitXml -OutputFile $pesterTestResultsFile -PassThru - (New-Object 'System.Net.WebClient').UploadFile("https://ci.appveyor.com/api/testresults/nunit/$($env:APPVEYOR_JOB_ID)", (Resolve-Path $pesterTestResultsFile)) - # Trying to fail the build, if there are problems - $errorString = '' - # All tests should pass - if ($res.FailedCount -gt 0) { - $errorString += "$($res.FailedCount) tests failed.`n" - } - # Documentation itself should be up-to-date - Update-MarkdownHelp -Path ./docs - $diff = git diff - if ($diff) { - $errorString += "Help is not up-to-date, run Update-MarkdownHelp: $diff`n" - } - if ($errorString) { - throw $errorString - } - -on_finish: - - ps: | - $ErrorActionPreference = 'Stop' - try { - $stagingDirectory = (Resolve-Path ..).Path - $zipFile = Join-Path $stagingDirectory "platyPS-$($env:APPVEYOR_BUILD_VERSION).zip" - Add-Type -assemblyname System.IO.Compression.FileSystem - 7z a -tzip $zipFile "$pwd\out\platyPS" - @( - # You can add other artifacts here - (ls $zipFile), - (ls .\out -File) - # flattering - ) | % {$_} | ? {$_} |% { Push-AppveyorArtifact $_.FullName } - } catch { - Write-Host -Foreground Red $_ - } diff --git a/build.ps1 b/build.ps1 deleted file mode 100644 index e9de3bca..00000000 --- a/build.ps1 +++ /dev/null @@ -1,86 +0,0 @@ -<# -.SYNOPSIS - Builds the MarkDown/MAML DLL and assembles the final package in out\platyPS. -#> -[CmdletBinding()] -param( - [ValidateSet('Debug', 'Release')] - $Configuration = "Debug", - [switch]$SkipDocs, - [string]$DotnetCli -) - -function Find-DotnetCli() -{ - [string] $DotnetCli = '' - $dotnetCmd = Get-Command dotnet - return $dotnetCmd.Path -} - - -if (-not $DotnetCli) { - $DotnetCli = Find-DotnetCli -} - -if (-not $DotnetCli) { - throw "dotnet cli is not found in PATH, install it from https://docs.microsoft.com/en-us/dotnet/core/tools" -} else { - Write-Host "Using dotnet from $DotnetCli" -} - -if (Get-Variable -Name IsCoreClr -ValueOnly -ErrorAction SilentlyContinue) { - $framework = 'netstandard1.6' -} else { - $framework = 'net451' -} - -& $DotnetCli publish ./src/Markdown.MAML -f $framework --output=$pwd/publish /p:Configuration=$Configuration - -$assemblyPaths = ( - (Resolve-Path "publish/Markdown.MAML.dll").Path, - (Resolve-Path "publish/YamlDotNet.dll").Path -) - -# copy artifacts -New-Item -Type Directory out -ErrorAction SilentlyContinue > $null -Copy-Item -Rec -Force src\platyPS out -foreach($assemblyPath in $assemblyPaths) -{ - $assemblyFileName = [System.IO.Path]::GetFileName($assemblyPath) - $outputPath = "out\platyPS\$assemblyFileName" - if ((-not (Test-Path $outputPath)) -or - (Test-Path $outputPath -OlderThan (Get-ChildItem $assemblyPath).LastWriteTime)) - { - Copy-Item $assemblyPath out\platyPS - } else { - Write-Host -Foreground Yellow "Skip $assemblyFileName copying" - } -} - -# copy schema file and docs -Copy-Item .\platyPS.schema.md out\platyPS -New-Item -Type Directory out\platyPS\docs -ErrorAction SilentlyContinue > $null -Copy-Item .\docs\* out\platyPS\docs\ - -# copy template files -New-Item -Type Directory out\platyPS\templates -ErrorAction SilentlyContinue > $null -Copy-Item .\templates\* out\platyPS\templates\ - -# put the right module version -if ($env:APPVEYOR_REPO_TAG_NAME) -{ - $manifest = cat -raw out\platyPS\platyPS.psd1 - $manifest = $manifest -replace "ModuleVersion = '0.0.1'", "ModuleVersion = '$($env:APPVEYOR_REPO_TAG_NAME)'" - Set-Content -Value $manifest -Path out\platyPS\platyPS.psd1 -Encoding Ascii -} - -# dogfooding: generate help for the module -Remove-Module platyPS -ErrorAction SilentlyContinue -Import-Module $pwd\out\platyPS - -if (-not $SkipDocs) { - New-ExternalHelp docs -OutputPath out\platyPS\en-US -Force - # reload module, to apply generated help - Import-Module $pwd\out\platyPS -Force -} - diff --git a/CHANGELOG.md b/docs/CHANGELOG.md similarity index 96% rename from CHANGELOG.md rename to docs/CHANGELOG.md index 930bbc0b..2c7d5434 100644 --- a/CHANGELOG.md +++ b/docs/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/CONTRIBUTING.md b/docs/CODE-LAYOUT.md similarity index 56% rename from CONTRIBUTING.md rename to docs/CODE-LAYOUT.md index acf23bba..c0a901cd 100644 --- a/CONTRIBUTING.md +++ b/docs/CODE-LAYOUT.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/docs/platyPS.schema.md b/docs/platyPS.schema.md new file mode 100644 index 00000000..9dd3878a --- /dev/null +++ b/docs/platyPS.schema.md @@ -0,0 +1,177 @@ +# Schema + +PlatyPS requires you to keep the content in a specific structure and Markdown notation. Any authoring must not break this formatting or the MAML will not be generated correctly. +It closely resembles output of `Get-Help`. + +## Legend + +- `{string}` - single-line string value +- `{{text}}` - multi-line text +- `//` - line comment in schema +- tabs show the scopes of `// for` statements; they should not be included in the Markdown output. + +### Version 2.0.0 + +``` +// Every cmdlet help placed in it's own `Command-Name.md` file in one folder. +// We sometimes reference to this folder as "HelpModule". + +// Top-level metadata. You can put your own "key: value" statements there +// unknown values would be ignored by platyPS +// You can query this data from markdown file with `Get-MarkdownMetadata` +// +// Keys that have meaning for platyPS have separate entries +--- +schema: 2.0.0 +external help file: {file name for `New-ExternalHelp`}.xml +online version: {url for `Get-Help -Online`} +applicable: {comma-separated list of tags where this cmdlet exists} // if omitted then applicable for any tag +{{ User-specific key-value pairs }} +--- + +# {Command name} + +// following level-2 headers sections can go in any order +// here is the recommended order + +## SYNOPSIS +{{Synopsis text}} + +## SYNTAX +// for each parameter set + ### {Parameter Set Name, if default parameter set, followed by "(Default)"} + // i.e.: FromPath (Default) + // This syntax would be ignored during maml generation. + // syntax would be generated from parameters metadata + ``` + {{Output of Get-Command -Syntax}} + ``` + +## DESCRIPTION +{{Description text}} + +## EXAMPLES +// for every example + ### {Example Name} + + {{Example introduction text}} + + // one or more times, codesnippet + // it's useful to put the ```powershell code + // before the plain text command execution output + ```{Syntax language, i.e. PowerShell or nothing for plain text} + {{Example body}} + ``` + + {{Example remarks}} // not a mandatory, i.e. TechNet articles don't use remarks + +## PARAMETERS + +// for every parameter + // default value is non-mandatory + ### -{Parameter name} + {{Parameter description text. It can also include codesnippets, but they could not be ```yaml}} + + // parameter metadata + // for every unique parameter metadata set + // Note: two Parameter Sets can have the same parameter as mandatory and non-mandatory + // then we put them in two yaml snippets. + // If they have the same metadata, we put them in one yaml snippet. + + ```yaml // this gives us key/value highlighting + Type: {Parameter type} // can be ommitted, then default assumed + Parameter sets: {comma-separated list of names, i.e. "SetName1, SetName2" or "(All)" + for all parameter sets} + Aliases: {comma-separated list of aliases, i.e. EA, ERR} // if ommitted => default + Accepted values: {ValidateSet, comma-separated list of valid values, i.e. Foo, Bar} + // if ommitted => everything is accepted + Applicable: {comma-separated list of tags where this cmdlet exists} + // if omitted then applicable for any tag + // break line to improve readability and separate metadata block + + Required: {true | false} + Position: {1..n} | named + Default value: {None | False (for switch parameters) | the actual default value} + Accept pipeline input: {false | true (ByValue, ByPropertyName)} + Accept wildcard characters: {true | false} + ``` + + // if supports workflow parameters + ### + {{ Workflow common parameters text, would be ignored during maml generation }} + + // if supports common parameters + ### + {{ Common parameters text, would be ignored during maml generation }} + +## INPUTS // for every input type +### {Input type} +{{Description text}} + +## OUTPUTS // for every output type + +### {Output type} +{{Description text}} + +## RELATED LINKS + +// for every link +[{link name}]({link url}) +``` + +### Version 1.0.0 (Deprecated) + +v0.7.6 is the last platyPS version that supports it. + +``` +// for every command: + # {Command name} + + // following level-2 headers sections can go in any order + // here is the recommended order + + ## SYNOPSIS + {{Synopsis text}} + + ## DESCRIPTION + {{Description text}} + + ## PARAMETERS + + // for every parameter + // type and default value are non-mandatory + ### {Parameter name} [{Parameter type}] = {Parameter default value} + + // parameter metadata + ```powershell + {{Parameter attributes as specified in param() block in PowerShell functions + i.e. [Parameter(ParameterSetName = 'ByName')] + }} + ``` + + {{Parameter description text}} + + ## INPUTS + // for every input type + ### {Input type} + {{Description text}} + + ## OUTPUTS + // for every output type + ### {Output type} + {{Description text}} + + ## EXAMPLES + // for every example + ### {Example Name} + + ```powershell + {{Example body}} + ``` + {{Example text explanation}} + + ## RELATED LINKS + + // for every link + [{link name}]({link url}) +``` diff --git a/docs/Get-HelpPreview.md b/docs/platyPS/Get-HelpPreview.md similarity index 100% rename from docs/Get-HelpPreview.md rename to docs/platyPS/Get-HelpPreview.md diff --git a/docs/Get-MarkdownMetadata.md b/docs/platyPS/Get-MarkdownMetadata.md similarity index 100% rename from docs/Get-MarkdownMetadata.md rename to docs/platyPS/Get-MarkdownMetadata.md diff --git a/docs/Merge-MarkdownHelp.md b/docs/platyPS/Merge-MarkdownHelp.md similarity index 100% rename from docs/Merge-MarkdownHelp.md rename to docs/platyPS/Merge-MarkdownHelp.md diff --git a/docs/New-ExternalHelp.md b/docs/platyPS/New-ExternalHelp.md similarity index 100% rename from docs/New-ExternalHelp.md rename to docs/platyPS/New-ExternalHelp.md diff --git a/docs/New-ExternalHelpCab.md b/docs/platyPS/New-ExternalHelpCab.md similarity index 100% rename from docs/New-ExternalHelpCab.md rename to docs/platyPS/New-ExternalHelpCab.md diff --git a/docs/New-MarkdownAboutHelp.md b/docs/platyPS/New-MarkdownAboutHelp.md similarity index 100% rename from docs/New-MarkdownAboutHelp.md rename to docs/platyPS/New-MarkdownAboutHelp.md diff --git a/docs/New-MarkdownHelp.md b/docs/platyPS/New-MarkdownHelp.md similarity index 100% rename from docs/New-MarkdownHelp.md rename to docs/platyPS/New-MarkdownHelp.md diff --git a/docs/New-YamlHelp.md b/docs/platyPS/New-YamlHelp.md similarity index 100% rename from docs/New-YamlHelp.md rename to docs/platyPS/New-YamlHelp.md diff --git a/docs/Update-MarkdownHelp.md b/docs/platyPS/Update-MarkdownHelp.md similarity index 100% rename from docs/Update-MarkdownHelp.md rename to docs/platyPS/Update-MarkdownHelp.md diff --git a/docs/Update-MarkdownHelpModule.md b/docs/platyPS/Update-MarkdownHelpModule.md similarity index 100% rename from docs/Update-MarkdownHelpModule.md rename to docs/platyPS/Update-MarkdownHelpModule.md diff --git a/docs/about_platyPS.md b/docs/platyPS/about_platyPS.md similarity index 100% rename from docs/about_platyPS.md rename to docs/platyPS/about_platyPS.md diff --git a/presentation/css/impress-demo.css b/docs/presentation/css/impress-demo.css similarity index 100% rename from presentation/css/impress-demo.css rename to docs/presentation/css/impress-demo.css diff --git a/presentation/images/FFFUUU.png b/docs/presentation/images/FFFUUU.png similarity index 100% rename from presentation/images/FFFUUU.png rename to docs/presentation/images/FFFUUU.png diff --git a/presentation/images/azure-maml.png b/docs/presentation/images/azure-maml.png similarity index 100% rename from presentation/images/azure-maml.png rename to docs/presentation/images/azure-maml.png diff --git a/presentation/images/get-help.png b/docs/presentation/images/get-help.png similarity index 100% rename from presentation/images/get-help.png rename to docs/presentation/images/get-help.png diff --git a/presentation/images/markdown-github.png b/docs/presentation/images/markdown-github.png similarity index 100% rename from presentation/images/markdown-github.png rename to docs/presentation/images/markdown-github.png diff --git a/presentation/images/markdown.png b/docs/presentation/images/markdown.png similarity index 100% rename from presentation/images/markdown.png rename to docs/presentation/images/markdown.png diff --git a/presentation/images/pscmdlethelpeditor.png b/docs/presentation/images/pscmdlethelpeditor.png similarity index 100% rename from presentation/images/pscmdlethelpeditor.png rename to docs/presentation/images/pscmdlethelpeditor.png diff --git a/presentation/images/psreadline-maml.png b/docs/presentation/images/psreadline-maml.png similarity index 100% rename from presentation/images/psreadline-maml.png rename to docs/presentation/images/psreadline-maml.png diff --git a/presentation/index.html b/docs/presentation/index.html similarity index 100% rename from presentation/index.html rename to docs/presentation/index.html diff --git a/presentation/js/impress.js b/docs/presentation/js/impress.js similarity index 100% rename from presentation/js/impress.js rename to docs/presentation/js/impress.js diff --git a/platyPS.schema.md b/platyPS.schema.md deleted file mode 100644 index 25b8d7f5..00000000 --- a/platyPS.schema.md +++ /dev/null @@ -1,168 +0,0 @@ -# Schema - -PlatyPS requires you to keep the content in a specific structure and Markdown notation. Any authoring must not break this formatting or the MAML will not be generated correctly. -It closely resembles output of `Get-Help`. - -## Legend - -* `{string}` - single-line string value -* `{{text}}` - multi-line text -* `//` - line comment in schema -* tabs show the scopes of `// for` statements; they should not be included in the Markdown output. - -### Version 2.0.0 - - // Every cmdlet help placed in it's own `Command-Name.md` file in one folder. - // We sometimes reference to this folder as "HelpModule". - - // Top-level metadata. You can put your own "key: value" statements there - // unknown values would be ignored by platyPS - // You can query this data from markdown file with `Get-MarkdownMetadata` - // - // Keys that have meaning for platyPS have separate entries - --- - schema: 2.0.0 - external help file: {file name for `New-ExternalHelp`}.xml - online version: {url for `Get-Help -Online`} - applicable: {comma-separated list of tags where this cmdlet exists} // if omitted then applicable for any tag - {{ User-specific key-value pairs }} - --- - - # {Command name} - - // following level-2 headers sections can go in any order - // here is the recommended order - - ## SYNOPSIS - {{Synopsis text}} - - ## SYNTAX - // for each parameter set - ### {Parameter Set Name, if default parameter set, followed by "(Default)"} - // i.e.: FromPath (Default) - // This syntax would be ignored during maml generation. - // syntax would be generated from parameters metadata - ``` - {{Output of Get-Command -Syntax}} - ``` - - ## DESCRIPTION - {{Description text}} - - ## EXAMPLES - // for every example - ### {Example Name} - - {{Example introduction text}} - - // one or more times, codesnippet - // it's useful to put the ```powershell code - // before the plain text command exectution output - ```{Syntax language, i.e. PowerShell or nothing for plain text} - {{Example body}} - ``` - - {{Example remarks}} // not a mandatory, i.e. TechNet articles don't use remarks - - ## PARAMETERS - - // for every parameter - // default value is non-mandatory - ### -{Parameter name} - {{Parameter description text. It can also include codesnippets, but they could not be ```yaml}} - - // parameter metadata - // for every unique parameter metadata set - // Note: two Parameter Sets can have the same parameter as mandatory and non-mandatory - // then we put them in two yaml snippets. - // If they have the same metadata, we put them in one yaml snippet. - ```yaml // this gives us key/value highlighting - Type: {Parameter type} // can be ommitted, then default assumed - Parameter sets: {comma-separated list of names, i.e. "SetName1, SetName2" or "(All)" for all parameter sets} - Aliases: {comma-separated list of aliases, i.e. EA, ERR} // if ommitted => default - Accepted values: {ValidateSet, comma-separated list of valid values, i.e. Foo, Bar} // if ommitted => everything is accepted - Applicable: {comma-separated list of tags where this cmdlet exists} // if omitted then applicable for any tag - // break line to improve readability and separate metadata block - - Required: {true | false} - Position: {1..n} | named - Default value: {None | False (for switch parameters) | the actual default value} - Accept pipeline input: {false | true (ByValue, ByPropertyName)} - Accept wildcard characters: {true | false} - ``` - // if supports workflow parameters - ### - {{ Workflow common parameters text, would be ingored during maml generation }} - - // if supports common parameters - ### - {{ Common parameters text, would be ingored during maml generation }} - - ## INPUTS - // for every input type - ### {Input type} - {{Description text}} - - ## OUTPUTS - // for every output type - ### {Output type} - {{Description text}} - - ## RELATED LINKS - - // for every link - [{link name}]({link url}) - -### Version 1.0.0 (Deprecated) -v0.7.6 is the last platyPS version that supports it. - - // for every command: - # {Command name} - - // following level-2 headers sections can go in any order - // here is the recommended order - - ## SYNOPSIS - {{Synopsis text}} - - ## DESCRIPTION - {{Description text}} - - ## PARAMETERS - - // for every parameter - // type and default value are non-mandatory - ### {Parameter name} [{Parameter type}] = {Parameter default value} - - // parameter metadata - ```powershell - {{Parameter attributes as specified in param() block in PowerShell functions - i.e. [Parameter(ParameterSetName = 'ByName')] - }} - ``` - - {{Parameter description text}} - - ## INPUTS - // for every input type - ### {Input type} - {{Description text}} - - ## OUTPUTS - // for every output type - ### {Output type} - {{Description text}} - - ## EXAMPLES - // for every example - ### {Example Name} - - ```powershell - {{Example body}} - ``` - {{Example text explanation}} - - ## RELATED LINKS - - // for every link - [{link name}]({link url}) 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