Add documentation

[iainbrighton]

There is little documentation, and where this is, it's incomplete. Need to complete the documentation before publishing to the Powershell Gallery.

[iainbrighton]

It would be good to externalise the help (rather than using comment-based help). This would help with localisation support if it's ever wanted/needed.

The PlatyPS project would certainly help with this. However, it would require a build process on the CI server (or a separate project completely) to ensure the help is updated with each commit. Note: this will probably be needed in the future to digitally sign the module's files when publishing to the gallery anyway..

It would also make it possible to support updateable help...

[kilasuit]

In addition I think it would be good to update the Readme to include any and all blogs on Lability as they in 1 way or another do provide a form of documentation

[it-praktyk]

I started play with

• AppVeyor - for continues integration
• Pester - for testing help structure
  for my OffCATcmd repository .

Currently for any commit help is parsed. In the next step I'll add invoking PlatyPS for build/update markdown files and pushing back to GitHub.

[it-praktyk]

Ping: @lazywinadmin

François-Xavier I would like add a code based on your blog post Using Pester to test your Comment Based Help to the Lability repository. Do you agree ?

[lazywinadmin]

@it-praktyk No problem Wojciech. Thanks for your comments btw, will check this week-end.

[it-praktyk]

Thank you @lazywinadmin !

@VirtualEngine , I put the first version of Pester tests for help in my Lability fork - as Tests/Help.Tests.ps1 .

I also generated the first version of markdown files generated by platyPS v. 0.5.0 module - in the Docs subfolder.

Discussion is needed

1. In what directory should I put Help.Tests.ps1 file before I will create pull request to your repository?
2. If any help structure - specially for a .NOTES section - was discussed by your team/contributors?
3. who should update existing functions? - some help parts are missed. You can see the tests results in the file Docs-Errors\Pester_Results.html

[iainbrighton]

Thanks @it-praktyk! The rendered Markdown looks pretty impressive 👍

How do you see PlatyPS being used here? Is the intention to produce Markdown files for online help/documentation? Or is the ultimate goal to move the existing help to Markdown, so that we can generate the MAML help files (that could be localized)? If it's the latter I wouldn't put too much effort into the comment based help tests..

[it-praktyk]

Thanks @iainbrighton :-)

The rendered Markdown looks pretty impressive

It's not my merit. Thanks @vors !

How do you see PlatyPS being used here?

I don't know better solution to produce markdown helps what can be translated to MAML next.

As my "sandbox" I use my OffCATcmd project. My goal is prepare solution to regenerate help files via AppVeyor if Pester tests pass.

What do you think about opening (automatically via GitHub API) issue when Pester tests for help structure fail?

BTW, I tried parse Pester results to text using Format-Pester but currently this doesn't work as expected for the text output. I opened issue . Your PScribo is used. Could you look ?

[it-praktyk]

I just added pull request #117 . I hope that failed Pester test will allow improve quality of help for the Lability module.

[makeitcloudy]

Lability is quite rough at the first place, but then it turned out to be a masterpiece. Thank you!