[it-praktyk]

The first version of markdown help files generated using the platyPS module
Pester test for a comment based help added. Required elements to pass all test

• SYNOPSIS - can't be empty
• DESCRIPTION - can't be empty
• all parameters included in the comment based help
• at least one example
• all examples need have description

[iainbrighton]

@it-praktyk I'm super excited with this! I'll publish the current dev branch to the gallery so that we can concentrate on getting this functionality merged in.

Is there any way we can get the function names put into the test result descriptions? At the moment, I can't see a way to determine where the errors are to fix them!

Note: I think there was a new PlatyPS build published last night?

[it-praktyk]

I'll work to prepare solution what will open the per function issue if help will not be parsed correctly.

The test results from the last Saturday, 2016-07-15.

[kilasuit]

@iainbrighton / @it-praktyk - I've been working on something similar in functionality as a generic set of Pester Tests for all my future modules - Will push a separate PR so that you can see if it would be useful here too although there is likely a fair amount of overlap with this PR so I would like to see if I can do some combining of the two first

[it-praktyk]

@kilasuit please check the list Pester related links - I try keep it updated. Maybe you will find there something helpful.

[it-praktyk]

The newer report tenerated by updated Format-Pester (still in development https://github.com/it-praktyk/Format-Pester/tree/dev

t)

[iainbrighton]

@it-praktyk That second report looks a lot better 😄. I'm happy to merge this in (with the failing build) to ensure that we fix the help for the next release.

I do have a query around the outstanding report though; should the help contain entries for the -WhatIf and -Confirm parameters? Do other MS cmdlets have custom help for those switches as they're common parameters?

[kilasuit]

@iainbrighton - this is where the issue lies as it should really be

$HelpParameters | Foreach-Object

However I've got a mitigation function for this called Get-CommonParameter in the PesterHelpers Module
https://github.com/PowerShellModules/PesterHelpers/blob/master/Private/Get/Get-CommonParameter.ps1

I then call it in the New-FunctionPesterTest function and basically remove all common parameters from the list of parameters to check on for help and other key information (in latest build being pushed shortly)

[kilasuit]

@iainbrighton - Also I've integrated the Help scenario that @it-praktyk raised into PesterHelpers this afternoon so there are a number of tests failing on this.

Perhaps this would be a good candidate to get merged into a separate branch for pulling all the documentation together?

[iainbrighton]

@kilasuit I'm happy for this work to be carried out in a separate branch. Question is: do I need to create that new branch or can you/@it-praktyk push a new branch?

[kilasuit]

@iainbrighton - Do you want the Good or Bad news??

Good news - All functions are exported with some non-functional Pester Tests like the Help tests that @it-praktyk has detailed in this PR.

Bad News - Currently I have the Non-Functional tests created for all functions (private & public) and there is quite a number of failing tests (mainly Private Functions) for missing Help etc but that is to be expected although I've built a smallish framework around this that allows us to decide the level of tests that you would want to run.

Will try and pull it altogether into a branch on my fork today and if you can create a new branch where I could submit a PR for it to here that would be great too.

[iainbrighton]

@kilasuit Whilst having help for private functions should be implemented, having a flag/parameter that can be set to skip/ignore certain tests for private functions will be needed. Note: I don't think you should be able to override the requirements for public functions. I also don't think that examples will be needed for private functions, but documenting the parameters for private functions should be a requirement (long term for the Lability project). Make sense?

[iainbrighton]

Oops. Wrong button! Sorry @it-praktyk @kilasuit 😊

[kilasuit]

Yes that makes perfect sense and that is exactly how I've built the framework to be flexible for the Idea of Long Term, Mid Term & Short Term enhancements and I'm currently writing up the blog post to explain the use cases and actual real world uses for going down this path in a simple and easy to repeat way on future modules that you may want to do this with as well.

Will ping you a preview of the blog post when its almost complete.

[it-praktyk]

@iainbrighton Is it possible to use PScribo like: Document { Document {} | Export-Document } | Export-Document to export subparts of document?

I've updated Format-Pester to group by Describe/Context and now I would like use text output to open GitHub issue(s) based on subparts.

[iainbrighton]

@it-praktyk I've logged this question over here iainbrighton/PScribo#23 so we can track it.

[iainbrighton]

So @it-praktyk and @kilasuit, what are we going to do with this PR? Do I need to create a new branch so that we can work on it there? Do we do this after I merge the DSC resource/module update in? Thoughts welcome 😉

[iainbrighton]

Sorry @it-praktyk and @kilasuit - there's a big merge that has happened on the dev branch that will no doubt have an impact on this PR. Can you pull in the latest changes and rerun the report as some cmdlets have been deprecated? PS - I'm off on hols for a couple of weeks, so nothing will happen until then :(

[it-praktyk]

As I declared I'll try prepare tool to opening issues based on Pester tests results and continous intergration. Have a good holidays!
That pull request was more like start of discussion so for me can be rejected.

[iainbrighton]

@it-praktyk Closing out for now. Please open a new pull request when you feel things are ready to go!