Move help to PlatyPS and generate pages of wiki based on it too

[nohwnd]

https://github.com/PowerShell/platyPS

[it-praktyk]

The related issue #648

The current state of help - after merging currently opened pull requests.

[Jaykul]

So ... if we think we want to do this, I think we should ...

Just Do It!

New-MarkdownHelp -Module Pester -OutputFolder Docs -WithModulePage

And then ask people to start helping us fix them.

[vors]

Would be great to see pester help in platyPS. Let me know if you find anything blocking transition.

[Jaykul]

Next step, clearly -- get people to help write help ;-)

[it-praktyk]

The related issue #555

[it-praktyk]

The related issue: Would you like to include API documentation to your build?.

[it-praktyk]

The related series of blog posts Automated Documentation in a CI/CD Pipeline for PowerShell Modules with PlatyPS, psake, AppVeyor, GitHub and ReadTheDocs by @markekraus

[nohwnd]

Anyone interested in implementing this or should we keep it as is and close it?

[it-praktyk]

I'll try to do that.

The related issue https://github.com/PowerShell/platyPS/issues/371

Wojciech Sciesinski

---

From: Jakub Jareš notifications@github.com Sent: Sunday, December 16, 2018 2:40:26 PM To: pester/Pester Cc: Wojciech Sciesinski; Comment Subject: Re: [pester/Pester] Move help to PlatyPS and generate pages of wiki based on it too (#720)

Anyone interested in implementing this or should we keep it as is and close it?

— You are receiving this because you commented. Reply to this email directly, view it on GitHubhttps://github.com/pester/Pester/issues/720#issuecomment-447648324, or mute the threadhttps://github.com/notifications/unsubscribe-auth/AErstcBBQFadi3P-AftZviKUJbAyWe_Jks5u5ltagaJpZM4LyVVn.

[nohwnd]

halbarad (discord) APP [1:04 PM] @PrzemyslawKlys @nohwnd, this is how I add it in:

#.ExternalHelp VMConfig-help.xml
Function Start-VmcLab {

There's another way using an attribute on the function but I always forget what it is. This is how I generate that xml from the md files.

New-ExternalHelp -Path $(Build.SourcesDirectory)\Docs -OutputPath ` 
    $(Build.SourcesDirectory)\Output\en

[PrzemyslawKlys]

I actually generate Docs folder for all my projects:

$null = New-MarkdownHelp -Module $ProjectName -WithModulePage -OutputFolder $DocumentationPath 

# and then update it
$null = Update-MarkdownHelpModule $DocumentationPath -RefreshModulePage -ModulePagePath $ReadMePath 

I've not played with XML yet as I don't really know how to host XML online for a module and how to pinpoint it to the module.

@nohwnd what you mentioned on twitter would be cool because right now it seems PlatyPS can take markdown help written inside a function (but not everything at least to my testing) and move it to docs folder, but having it work another way around would be great too.

[nohwnd]

The problem I am trying to solve is how to keep the documentation up to date, trackable and easy to update. These days I am working on Pester v5 and I am removing and renaming a lot of stuff. Migrating from v4 to v5 will take some until we can safely retire v4, so having two versions of wiki is definitely needed. And the other thing is that scrolling past inline help is extremely annoying, especially since there are many functions in one file it's not very easy to see in which function I currently am.

On the other hand I like that the wiki is easy to edit.

@it-praktyk how far are you with this?:)

[Splaxi]

Would it be enough to have the format of the documentation based on the CBH and from that generate either External-Help and Wiki pages?

[PrzemyslawKlys]

The functions I showed you will first create docs and then you use just Update-MarkdownHelpModule anytime you make a change. It will take any parameters and update it in Docs folder. It looks like this:

https://github.com/EvotecIT/PSWinReporting/tree/master/Docs

Any time you make an update, rerun the function and it will add missing files, parameters and generally fix it. What it doesn't do is update it back within the function so you would have to copy manually back, or have some kind of script that foreach Docs\md file find the corresponding function and add it there.

I've not found other way to do that.

[Splaxi]

@PrzemyslawKlys

I do the same for my modules.

I keep all my documentation in CBH and have the docs generated based on that.

https://github.com/d365collaborative/d365fo.tools/tree/development/docs

[nohwnd]

I think there is way more stuff in wiki than what would be reasonable for comment based help. I would also like to write wiki and help at the same time, so they agree. Maybe there could be some markings that I use to generate help, and remove in post processing. like <!--- Example 1 start --->, or <!--- parameter -Skip ---> ?

[PrzemyslawKlys]

There are already markings .Example marking is start, next .EXAMPLE is another marking. PlatyPS is able to work with those markings and copies them from original codebase.

[it-praktyk]

@it-praktyk how far are you with this?:)

Not so far, I just generated files using PlatyPS - you can find the branch https://github.com/it-praktyk/Pester/tree/PlatyPS_Help.

[it-praktyk]

How do I see a process of migration to a markdown-based help?

1. Create the branch PlatyPS_help in the repository Pester/Pester - to make work visible

2. Update CI pipeline to trigger Update-MarkdownHelpModule (please be aware of the issue PowerShell/platyPS#371 - as long as the step 5 will not be completed it's not the case but later ...

3. Verify/clean the content of markdown files.

4. Generate XML MAML-formated help files based at markdown and include them in the release

5. Remove a command-based help from the *.ps1 files

[fourpastmidnight]

I was totally going to attempt this myself. I didn't want two sources of truth for help in my own modules, and so early on, I decided to not use comment-based help in my functions, but instead write the markdown documents and use platyPS to generate the help file for my module. I was hoping to do the same for Pester--but my time is limited and I see that there are already ppl working on/interested in making this happen! I'd be happy to lend any help and support for this effort.

[Splaxi]

@fourpastmidnight If you could share what you have already, it would make it easier for us to skip in making it happen.

[nohwnd]

So here is a move-help-to-platyps branch if more people want to work on this. The help should be in Markdown, and the comment based help would be generated from it. I would start with moving the help into it's own files, and then we can start talking about possibly making the wiki and the help using the same sources, or integrating in some way. Any takers?

[it-praktyk]

I'll make an initial work just now :-)

[it-praktyk]

Done, PR #1226.

[nohwnd]

@it-praktyk k merged, only scrolled through the changes, and the first file looked broken, some extra type escaping there and incorrect code regions, but I will review properly when this is ready to merge to master.

[it-praktyk]

I work now to clean 'RELATED LINKS' sections and doubled empty lines.

Done. 48c73795a2ea7db107b00666522132f690a7555c

[it-praktyk]

Please be aware of the issue with Update-MarkdownHelp - https://github.com/PowerShell/platyPS/issues/433.

[it-praktyk]

@nohwnd, I'm thinking about reverting your change regarding the structure of MD files - I'm thinking about undoing your change regarding the structure of MD files.

Some (all?) of changes will be reverted under the next update made by using Update-MarkdownHelp - please read the thread https://github.com/PowerShell/platyPS/issues/345.

[nohwnd]

@it-praktyk I am probably getting this wrong, but I thought that new-markdown help generates the markdown files from the existing files once. And then we use something different to convert the existing markdown files back to the powershell help. So formatting the markdown properly should not be a problem, because we will be using the markdown as the source of the help for the cmdlets, and not the other way around, in other words the markdown will never be regenerated again.

Or that is not how it works?

[it-praktyk]

IMHO, Update-MarkdownHelp workflow is like below.

1. read the existing markdown help file
2. parse markdown to PSObject
3. get information about parameters from the code
4. merge 2 + 3
5. write the file

@vors, Am I right?

The related issue: https://github.com/PowerShell/platyPS/issues/393

[PrzemyslawKlys]

You need to continue using Update-MarkdownHelp if you want to have all the benefits of it. Otherwise everytime you will change order, add parameters you will have to update docs manually. It's best to keep to the specs that platyPS proposes.

[nohwnd]

Okay gotcha, I confused New-MarkdownHelp with Update-MarkdownHelp

[PrzemyslawKlys]

We can always help and bring new features to PlatyPS 👍 I'm sure @vors will be happy!

[fourpastmidnight]

Sorry I didn't reply yet, things have been crazy at work. I did take the option of not using Update-MarkdownHelp because of the formatting issues you all have been experiencing. Though as mentioned, going that route means the onus is on contributors to update the help properly.

The one major reason I did that, though, was to eliminate comment based help in the code which took up too much space. And, I'd still need to update comment based help, then update markdown help, then reformat the generated markdown anyway...too much work. I figured manually updating the markdown was going to be no more effort in most cases. Plus, I was unsure how platyPS would handle multiline code examples since, in comment based help, that is not possible anyway but is often something you need (should do) for clarity; however, this is possible when updating the help files directly instead of always regretting them from comment based help.

Anyway, that's my $0.02...

[fourpastmidnight]

@nohwnd so yes, that implies you can generate the help once and then use the markdown as the primary source from which to generate help for the build. When I get into the office in about one hour, I'll quick dig up the psake task I'm using to do just that.

[PrzemyslawKlys]

Here is generated content by New / Update

https://github.com/EvotecIT/PSEventViewer/blob/master/Docs/Get-EventsInformation.md

As you can see there are several examples. It actually converted the content from https://github.com/EvotecIT/PSEventViewer/blob/master/Public/Get-EventsInformation.ps1 including comments under examples. Seems good enough right?

[fourpastmidnight]

@PrzemyslawKlys Hmm, I recalled having difficulty with that--but glad to see it seems to be working. Though, the example you linked to didn't have code + text. I think it's that interplay between code/non-code text that may trip up platyPS? I don't really remember.

Here's my psake task for generating help, which probably already looks very much like what you're already doing:

Task GenerateModuleHelp {
    [string[]]$helpDocs = @(Get-ChildItem $DocsDirectory -File -Filter "*.md" -Recurse | Select-Object -ExpandProperty FullName)

    New-ExternalHelp -Path $helpDocs -OutputPath "${ENV:BHPSModulePath}\en-US"
}

I'm also using the BuildHelpers module which simplifies things for me--that's all those $ENV:BH* variables.

So, I first ran whatever cmdlet to run to convert my existing comment-based help to Markdown, tweaked the markdown, and now I only use New-ExternalHelp. Otherwise, I maintain the markdown manually at this point. I haven't used this long enough to have any regrets--maybe someone else has? Anyway, guess I'm not really contributing much, as you guys already have this--and by the way, good job to all who have taken point on this.

[PrzemyslawKlys]

I believe it takes everything under .Example as code you can see that in my example

[PrzemyslawKlys]

And actually, if you modify the output .md file as I did now it doesn't change it back. https://github.com/EvotecIT/PSEventViewer/blob/master/Docs/Get-EventsInformation.md

So I would say as long as you conform to some rules you should be fine.

[PrzemyslawKlys]

Just to make it clear. I am using Update-MarkdownHelpModule not Update-MarkdownHelp which has different behavior.

[fourpastmidnight]

Oh, hmm, I'll have to read up on that. Thanks for the info!

[fourpastmidnight]

Question, though: Are we, in the end, going to remove the comment-based help from the *.ps1 files and use the Markdown files as "the source of truth"? Or is the plan to continue to use comment-based help and generate changes to the markdown using Update-MarkdownHelpModule?

[nohwnd]

As you say. Help in markdown only.

[it-praktyk]

I need help to find why some tests fail in the branch move-help-to-platyps

  Assertion operators                                                                                                                                                                                                                           
    [-] Allows an operator with an identical name and test to be re-registered 39ms                                                                                                                                                             
      Expected no exception to be thrown, but an exception "Assertion operator name 'SameNameAndScript' has been added multiple times." was thrown from C:\Users\<FOLDER_PATH>\Pester\Pester.psm1:484 char:13     
          +             throw "Assertion operator name '$string' has been added m ...                                                                                                                                                           
          +             ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~.                                                                                                                                                              
      352:             } } | Should -Not -Throw                                                                                                                                                                                                 
      at <ScriptBlock>, C:\Users\<FOLDER_PATH>\Pester\Pester.Tests.ps1: line 350                                                                                                                                  
    [-] Allows an operator with an identical name, test, and alias to be re-registered 30ms                                                                                                                                                     
      Expected no exception to be thrown, but an exception "Assertion operator name 'SameNameAndScriptAndAlias' has been added multiple times." was thrown from C:\Users\<FOLDER_PATH>\Pester\Pester.psm1:484 char
:13                                                                                                                                                                                                                                             
          +             throw "Assertion operator name '$string' has been added m ...                                                                                                                                                           
          +             ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~.                                                                                                                                                              
      362:             } -Alias SameAlias } | Should -Not -Throw                                                                                                                                                                                
      at <ScriptBlock>, C:\Users\<FOLDER_PATH>\Pester\Pester.Tests.ps1: line 360                                                                                                                                  
    [+] Allows an operator to be registered with multiple aliases 23ms                                                                                                                                                                          
    [+] Does not allow an operator with a different test to be registered using an existing name 20ms                                                                                                                                           
    [+] Does not allow an operator with a different test to be registered using an existing alias 45ms                                                                                                                                          

I've reverted, locally, the commit e8f5722ad289d3895762ab00025ca3f016433d89 but it still fails.

I propose to exclude the tag Help under Invoke-Pester.

[nohwnd]

The registration fails when assertion has the same name but different content in the scriptblock, are you registering the operators twice, each with different body?

[it-praktyk]

It's a part of the standard Pester tests. Under changing help (and the code reformatting, in some cases).

I broke something during my actions :-/

[nohwnd]

Keep it failing I can have a look on it later. :)

[nohwnd]

We created https://pester.dev in the meantime.