platyPS documentation and Profile conversion #2932
Conversation
cormacpayne
changed the title
cormacpayne
changed the title
|
|
||
| ## Description | ||
|
|
||
| PlatyPS is used to create PowerShell external help in markdown rather than MAML. Where as MAML can be difficult to edit by hand or read, markdown is designed to be human-readable and easy to edit. This will allow service teams to quickly and easily edit any help documentation they have for their cmdlets. |
There was a problem hiding this comment.
... rather than XML (MAML). Whereas powershell XML help (MAML) can be difficult to read, edit, or review in github, ...
Our users do not really know that MAML is the name of the Xml schema for PowerShell help, so I would avois making it too prominent
| ``` | ||
| then the markdown files will be generated from the information in the MAML file (found in the module) **and** using reflection on the cmdlet implementation in the module. | ||
|
|
||
| #### NOTE |
There was a problem hiding this comment.
I would refer to this note here and place the note itself further down in the document. It detracts a little bit from the flow of figuring out what I need to do
| - [How it Works](#how-it-works) | ||
| - [Creating markdown](#creating-markdown) | ||
| - [Updating markdown](#updating-markdown) | ||
| - [Updating MAML](#updating-maml) |
There was a problem hiding this comment.
This has been changed.
| - [Creating markdown](#creating-markdown) | ||
| - [Updating markdown](#updating-markdown) | ||
| - [Updating MAML](#updating-maml) | ||
| - [Previewing MAML](#previewing-maml) |
There was a problem hiding this comment.
This has been changed.
| - [Updating markdown](#updating-markdown) | ||
| - [Updating MAML](#updating-maml) | ||
| - [Previewing MAML](#previewing-maml) | ||
| - [Getting Started](#getting-started) |
There was a problem hiding this comment.
I would put the 'Getting Started' section above 'How it Works'
| $idx++ | ||
|
|
||
| # Check each line between SYNOPSIS and SYNTAX for any text | ||
| for (;;) |
There was a problem hiding this comment.
why not do the for over all lines in the file and break if synopsis is found? What happens if idx is past the length of the array (i.e. there is no syntax)?
There was a problem hiding this comment.
I believe that each of the major sections (synopsis, syntax, description, etc.) is always generated by platyPS, regardless of whether or not there is corresponding information for it. In that case, it is guaranteed to have a synopsis section and a syntax section, so this for-loop will always be triggered and will always terminate.
| for (;;) | ||
| { | ||
| $foundSynopsis = $foundSynopsis -or (!([string]::IsNullOrWhiteSpace("$($content[$idx])"))) | ||
|
|
There was a problem hiding this comment.
You might consider using a regular expression and the C# Regex class for each of these. You can see examples of usage in the PublishModules script.
| # Check each line between OUTPUTS and NOTES for any text | ||
| for (;;) | ||
| { | ||
| $foundOutput = $foundOutput -or (!([string]::IsNullOrWhiteSpace("$($content[$idx])"))) |
There was a problem hiding this comment.
Not all commands produce output, so we might consider this as a warning.
There was a problem hiding this comment.
That was something I thought about but didn't continue with. I will find a way to separate the output warnings from the regular errors in the script.
| # If the markdown file had any missing help, add them to the list to be printed later | ||
| if ($fileErrors.Count -gt 0) | ||
| { | ||
| $errors += $file |
There was a problem hiding this comment.
It would be nice to have a readble format for this:
=========
File: Get-AzureRMWidget.md
-- Syntax missing
| where `$service` is the name of your service (*e.g.,* Profile, Compute, Network, etc.) and `$pathToRepo` is the path to the **azure-powershell** repo locally on your machine. | ||
|
|
||
| This script can be used for new services looking to create markdown files, or services looking to update their existing markdown files. | ||
|
|
There was a problem hiding this comment.
Can we suggest a good editor for editing / visualizing markdown?
|
@cormacpayne Looks liek soem of the help comments havn't been addressed. Is this ready to review otherwise? |
| @@ -0,0 +1,22 @@ | |||
| --- | |||
There was a problem hiding this comment.
This is the module page that is generated by platyPS when the markdown files are initially created. It is used when Update-MarkdownHelpModule is executed.
| [Parameter(ParameterSetName="ResourceManager", Mandatory=$True)] | ||
| [Parameter(ParameterSetName="ServiceManagement", Mandatory=$True)] | ||
| [Parameter(ParameterSetName="Storage", Mandatory=$True)] | ||
| [String]$PathToRepo, |
There was a problem hiding this comment.
Now that this is a module, you shouldn't need this info, so this can be optional. To get the directory that contains your module, use:
$PSModule = $ExecutionContext.SessionState.Module
$PSModuleRoot = $PSModule.ModuleBase
Using this, we should be able to remove this as a required parameter
| [String]$PathToCommandsFolder, | ||
|
|
||
| [Parameter(ParameterSetName="FullPath", Mandatory=$True)] | ||
| [String]$ModuleName |
There was a problem hiding this comment.
Can we infer this from PathToModule?
There was a problem hiding this comment.
Note that these parameter comments apply everywhere
| [Parameter(ParameterSetName="ResourceManager", Mandatory=$True)] | ||
| [Parameter(ParameterSetName="ServiceManagement", Mandatory=$True)] | ||
| [Parameter(ParameterSetName="Storage", Mandatory=$True)] | ||
| [String]$PathToRepo, |
| [String]$PathToCommandsFolder, | ||
|
|
||
| [Parameter(ParameterSetName="FullPath", Mandatory=$True)] | ||
| [String]$ModuleName |
| ) | ||
|
|
||
| $dlls = @{ | ||
| "Automation" = "Automation\Microsoft.Azure.Commands.Automation.dll"; |
| [String]$PathToModule | ||
| ) | ||
|
|
||
| for (;;) |
There was a problem hiding this comment.
Note that you can use the Get-Item commands to treat paths as files and extract properties, see: https://github.com/Azure/azure-powershell/blob/dev/tools/PublishModules.ps1#L183
| [Parameter(ParameterSetName="ResourceManager", Mandatory=$True)] | ||
| [Parameter(ParameterSetName="ServiceManagement", Mandatory=$True)] | ||
| [Parameter(ParameterSetName="Storage", Mandatory=$True)] | ||
| [String]$PathToRepo, |
| [String]$PathToHelp, | ||
|
|
||
| [Parameter(ParameterSetName="FullPath", Mandatory=$True)] | ||
| [String]$ModuleName |
There was a problem hiding this comment.
Also, please make md changes as suggested in previous review
|
@markcowl addressed new code review comments. What are the md changes that you suggested in the previous review that were not resolved? |
Comments
Fix for issue #2921
platyPS is a tool used to convert the current MAML help files into individual markdown files for each cmdlet in a service. This allows partners to easily edit the help for cmdlets using markdown rather than MAML.
This commit contains documentation on how to use the platyPS tool to make these changes, as well as scripts that will help a service team generate these markdown files and validate that they have all of the necessary help information for each cmdlet.
This commit also converts Profile to the markdown help, which will need to be updated in a separate PR.
This checklist is used to make sure that common issues in a pull request are covered by the creator. You can find a more complete discussion of PowerShell cmdlet best practices here.
Below in Overall Changes, check off the boxes that apply to your PR. For the categories that you did not check off, you can remove them from this body. Within each of the categories that you did select, make sure that you can check off all of the boxes.
For information on cleaning up the commits in your pull request, click here.
Overall Changes
General
Tests