Incorporate PowerShell Help into SDK

[glenncarr]

We're using Sandcastle to generate .NET documentation for our product API - works great, although we're still on an older version.

I'm using an old but still operational utility PoshBuild (https://poshbuild.codeplex.com/) to generate MAML help from our PowerShell module assembly so that we can automatically update the help displayed in PowerShell for our custom commands. Is there any way to incorporate this MAML output into help output such as a chm and html help?

Also, we're reluctant to upgrade to the latest version simply because the naming convention for white paper / conceptual topics will be converted to GUIDs. Is there no way to preserve the topic title in the name of the URL instead of the GUID?

Thanks,
Glenn

[EWSoftware]

I'm not familiar with PowerShell or its help format. Whether or not you can use the topics it uses depends on their format and how consistent it is with the MAML used in SHFB. It's possible you could create a plug-in for SHFB that perhaps takes the output from that and inserts it into placeholder topics in the SHFB project or something like that. There may be a better way but I can't say without knowing more about what there is to work with.

Regarding upgrading, that shouldn't be an issue. The requirement that topic IDs be GUIDs was dropped a long time ago. GUIDs are the default for topic IDs but you can change them to a more human readable string if you like as long as they're unique across all topics. If you're converting HTML files to MAML using the HTML to MAML Converter, it will use GUIDs for the new topics but you can replace those as you see fit and update the content layout file by reassociating the files with the topics afterwards.

[glenncarr]

Thanks for the response.

Attached is a zip file containing MAML for one command to just to give you an example.
Progistics.Management.dll-Help.zip

This article - https://www.red-gate.com/simple-talk/dotnet/software-tools/documenting-your-powershell-binary-cmdlets/ - is a pretty good description of what I'm doing. Although this isn't the utility I use (I use PoshBuild), it appears to work the same as PoshBuild - pulling documentation from comments into a MAML XML file that PowerShell will use when help is requested for a command - Help <custom-cmdlet>.

I'll look at using topic names - I upgraded some very old RoboHelp content to the latest version of SHFB recently, and I didn't see how to do that.

Thanks again.

[vors]

@glenncarr sorry for a shameless plug, I think you may like https://github.com/PowerShell/platyPS for handling the PowerShell help. It's used by projects like https://github.com/Azure/azure-powershell and https://github.com/lzybkr/PSReadLine .

[glenncarr]

@vors very interesting; thanks for the info! Looks very promising for our project. I'll take a closer look.