Add help + Wiki page

[Stephanevg]

All commandlets have Comment based help + examples
It would be great to have help extracted into individual markdown pages (using PlatyPS for example).

[tigerfansga]

I don't mind working on this. Just a few questions.

1. Do you want to convert the existing Comment based help to markdown, them remove them from the functions? (that way it's maintained in one place)
2. There is Comment based help in a few of your private functions, what would you want to do with those?
3. You build process is contained in appvoyer.yml, would you want me to update that as well or leave that to you?

I work on these things in my off time, so it might take me a few weeks (definitely before the end of #hacktoberfest

[Stephanevg]

Hi @tigerfansga
Great, it is all yours! to answer your questions:

1. Do you want to convert the existing Comment based help to markdown, them remove them from the functions? (that way it's maintained in one place)

• Absolutley not It is important to leave the comment based help in the functions, as it gives help to the users directly in the console using "Get-Help" ;)

2. There is Comment based help in a few of your private functions, what would you want to do with those?

• I think that these ones should not be offered to the public, as the internal classes / functions are there to help the developpers only. If a dev needs more info about one of the private functions, I bet he knows where to get that info ;)

I think we could agree, and say we want only to generate the help files from functions that are located in the Public folder (https://github.com/Stephanevg/PSClassUtils/tree/master/Functions/Public )

In powershell, this would probably be:

Get-childItem -Path $PsScriptRoot\Functions\Public

3. You build process is contained in appvoyer.yml, would you want me to update that as well or leave that to you?

• It could be very interesting to have something automated, indeed. Having it in there would be awesome. I think this could be a complete task (issue) (with a resulting PR) in itself.
  Perhaps it makes sense to create an issue to track this seperatley so that this could be done in a second step?

[tigerfansga]

Thanks @Stephanevg

I will get to working on it. One thing on answer #1, so if you look at the README.md for PlatyPS it gives two "Common setups" 1. Using markdown as the source of truth and generate compiled help - this is what I was thinking of when I asked about removing the comment based help, help would still be available for the user - or 2. Keeping comment based help and generating markdown. Based on your answer, I will go with path 2 unless you decide otherwise.

I don't mind working on issue #16 after the help part is done.

I definitely don't mind look at some automation. Maybe moving to something like psake for your build process. It would simplify the yaml

[Stephanevg]

Cool!
Yeah, so defenitley step 2 when regards to platyPS 'common setup'.
Issue 16 would be the logical next step, indeed. You can directly go ahead and takle that one as well.
If you have any questions, don't hesitate to ask them here :)

[tigerfansga]

I will do. I updated my last comment because I had missed the automation piece. Take a look for future ideas on automation.

[tigerfansga]

Hi @Stephanevg

Wanted to give you a quick status. First, my normal development environment is using a Ubuntu machine with PSCore 6.1. I have forked the project and created a branch issue-15. I have done a quick first pass using platyPS. Just a few items of note.

1. The module wouldn't initially load because in PSClassUtils.psm1 your loader loop had an issue - one that would only show up on Linux - public instead of Public for the path. I corrected in my branch.
2. platyPS threw an error when I generated the output. My guess this error was platform related. It did generate markdown files for everything.
3. Take a look at the docs. This is exactly what platyPS generated New-MarkdownHelp -Module PSClassUtils -OutputFolder ./docs -Force This is the unedited output

It may take me a few days, but I will setup a Windows environment to make sure there are no platform issues.

[Stephanevg]

Hi @tigerfansga
awesome to see you making progress so fast!

To address your topics:

1. I actually never tested the module on Linux. It is pretty interesting to have your feedback abou that.
   Case sensitivity is something that will end up to be problematic on Linux. In my opinion, making this module portable on Linux is a whol topic in it self. I'll open a specific issue to track that.

2. I am not about the error of platyps, and couldn't find anything on their start page saying that the module is not 'linux' friendly. Perhaps it would be a good thing to file an issue there; You might have found a bug?

3. The files look good, but I realized we will have to clean up the comment based help a bit from the functions.

Here are my remarks, directly on a screen shot. Each topic is anotated with 'a', 'b' etc.. so we can discuss easily about these topics.

Also, the Notes sections isn't that nicely formatted. Any idea how we could make it prettier?

A lost thing, I saw you have help for the function 'ConvertTo-TitleCase'. That is actually a private function, and it should not be in the files.
I think you can simply specify the path to the location where the public functions are stored (https://github.com/tigerfansga/PSClassUtils/tree/master/Functions/Public)

[tigerfansga]

Hi @Stephanevg

1. Once I learn more about your actual module, I'll see where the gaps are.
2. Too early to know where the issue is. PowerShell Core doesn't have feature parity with Windows Powershell. (see answer c below)
3. I can help there once I'm more familiar with your module. Also, my goal is to have the build of the markdown files be automated so as the comment based help is cleaned up, it will transfer to the markdown.

On your remarks
a. Not sure, like I just dumped the output of platyPS, did a quick scan to see that the output wasn't empty and pushed it up for review.
b. I will play with it and see what is needed.
c. I think this is the result of the error. The error was complaining about not finding the AST for one of the classes. I will rerun the command on Windows and see what I get.

I will look at the Notes to see what needs to be done. On the Private functions, again I just did a quick pass, once automated these will be gone.

[Stephanevg]

ok, awesome! 👍
Looking forward for it then! :)

[tigerfansga]

So on item b above, it is related to the way markdown is interpreting the -‘s used to format the comment based help. I will have to play with it some more to see how to fix it

[Stephanevg]

hi @tigerfansga have you any news on this one?

[tigerfansga]

Sorry, I’ve not had much chance to look. This weekend I should.

[tigerfansga]

Evening @Stephanevg

I spent a little time today playing with this. Main item learned, the output from PlatyPS is different on Linux than Windows. One must always keep in mind PSCore, especially on Linux or MacOS is not the same as Windows PowerShell. The markdown generated is much closer to the comment based help when run from Windows PowerShell.

There are still a few things that don't convert exactly right. The big item is the formatting of the examples. Markdown doesn't treat spaces the same as comment based help does. I will start to research how we can make things line up properly. We will probably have to modify the current comment based help to have it match up.

My current plan is to get the comment based help to generate the markdown to match and update the CI to run the commands to generate the markdown.

I have pushed the output of New-MarkdownHelp to my working branch I've only spot checked at this point.

[PeterMTaylor]

Could I ask for some use case examples when you mentioned " comment based help to generate the markdown"