[Feature Request] Subfolders

[homotechsual]

I have a few complex PS modules with 20-60 cmdlets, for the sake of clarity and discoverability we tend to group these by verb. Since discovering this module (phenomenal work btw!) I've added the ability to group cmdlets by verb in the resulting documentation as well as reflecting appropriately in the resulting sidebar with category pages. Would this be a useful addition to PR?

[homotechsual]

From this:

To this:

[bravo-kernel]

Never thought about this but that is so smart, simply love it. Feel free to PR a switch parameter.

Bonus points if you can throw in a unit test to make sure that the "default" sidebar behavior does not break.

[bravo-kernel]

@fflaten @nohwnd

[fflaten]

@bravo-kernel Thanks for the tip. Personally don't think it's relevant for Pester due to DSL-type functions, but I fully support as optional feature for other modules 👏

@homotechsual Did you use a 2 or greater cmdlet threshold per group? Does it make sense to make it configurable in the feature? Personally I'd probably group all to please my OCD 😄

[homotechsual]

I had it configurable in my "quick and dirty" setup and would probably keep it as such.

[homotechsual]

I'm currently trying to work out how much work it might be to have it a bit more open ended to allow for grouping by something other than "verb".

I've been thinking about the benefits potentially of grouping by "entity" but I'm not sure how I can easily "parse" that. I suppose the simplest option might be to group the same way as the source tree so that's my current exploration angle.

[homotechsual]

The above is probably a pipe dream as we don't really have that information but it's fun to think about :-)

[bravo-kernel]

@homotechsual if you want to give this a shot it would be great. Making the default non-discriminatory (and thus not 2+) would be my preference as suggested by @fflaten. Once the basics are in we can take it from there.

-GroupByVerb ?

[bravo-kernel]

@fflaten I have never seen or touched a DSL-type function but those would be AfterAll, AfterEach, BeforeEach, Should, etc correct?

-GroupByPascalCase but... I now see it indeed makes no sense. 👍

[fflaten]

@fflaten I have never seen or touched a DSL-type function but those would be AfterAll, AfterEach, BeforeEach, Should, etc correct?

Yeah, domain-specific language. Basically specialized keywords unique to Pester, like the main building blocks It, Describe and Context.

[fflaten]

A few suggestions, though it might belong in a separate issue and/or follow-up PR:

• Could we allow custom groups? E.g. a dictionary with group title = regex-pattern? Ex. @{ 'Retrieve data' = '^Get-.*'; 'Update data' = '^Set-.*' } while unmatched files stays in the root
• Can files stay flat? Subfolders change URLs which breaks links
  • Or include option to set slug: ../filename etc. to override the URL back to commands root

Scenario: Might consider this for Pester v6 to group many Should-* commands, while keeping the rest in the original flat structure. Don't want to break existing URLs.

If this is too edge case I'm fine with post-processing the sidebar-file, but worth suggesting while this has an active PR 🙂

[bravo-kernel]

@fflaten feel free to implement this (as a separate PR). Not being lazy but the feature is still very valid but think it will require some (more) advanced PowerShell skills to get it done right.