Show documentation on custom rules

[mcgurdan]

I have noticed the new support for Show documentation for pops up as a suggested correction. However, when using custom rules this uses this github repo and results in a 404 (e.g. https://github.com/PowerShell/PSScriptAnalyzer/blob/development/RuleDocumentation/Measure-PascalCase.md). Is it possible to use a custom url for this feature? This would allow us to direct the documentation at our own internal spaces.

[bergmeister]

We would need to either abuse an existing property in DiagnosticRecord or create a new property or optional constructor parameter (which would require a new version of PSSA), I think the latter is the better option unless there is an unused property. After this we would also need a PR each in PowerShellEditorServices and powershell-vscode...
Feel free to submit a PR for that

[jegannathanmaniganadan]

It would be great to have this customization. I have been looking for customizing this url.

[mcgurdan]

It’s fairly trivial to extend, I’ll try to find the time

[bergmeister]

Awesome, go for it. Please note that at the moment, only the Windows build images work (a PR is open to fix the Ubuntu build), therefore it is normal that 1 of the 4 build matrix elements will be read resulting in the build appearing to be red, please ignore that for moment

[jegannathanmaniganadan]

Perfect! Looking forward on this

[jegannathanmaniganadan]

If someone can brief me about the changes we expect, I can give it a try. At least the main script that needs a change.

[mcgurdan]

Sorry, I'll pick this up today

[bergmeister]

Cc @rkeithhill Just FYI as we'll need also a PRs in PSES and the vscode extension

[mcgurdan]

So I have a working solution for this, however, it might not be for everyone unfortunately. As @bergmeister mentioned, in order to make this change, it involves making changes to PSES and VSCode, which in turn would probably then call for an extension to the diagnostic records here to include a custom URL, in an ideal world this is how I would it (however, I just don't have the time),

In the interest of time I opted for the solution below, maybe this will be of some use to someone else.

1. We (myself and my colleagues) use an internal wiki space for documentation
2. I have specifically named all of our internal rules to match our naming schema Verb-PrefixNoun
3. I have updated the CodeAction.js found in "$env:USERPROFILE.vscode\extensions\ms-vscode.powershell-2019.5.0\out\src\features\CodeActions.js"
4. The update is for the function showRuleDocumentation

• The function already makes use if (ruleId.startsWith("PS")) -> I simply extended this logic to something similar where if the ruleId matches our Prefix we update pssaDocBaseURL to point our internal wiki (I removed it from being a Const).

Now, VSCode goes to this GitHub for all PSScriptAnalyzer rules and our Wiki for internal rules!

I know this is a little, hacky but fairly simple to implement at build time for us (we use chocolatey). Hope this helps anyone that might be interested.

[jegannathanmaniganadan]

Nice!

[bergmeister]

This 'working solution' is a really bad hack and I strongly recommend against using it. The ms-vscode.powershell has been a bit quiet in the last months with releases but generally expect a release every other month. Every release will break your 'solution' because the extension will be auto-updated in the background without you noticing and replace the code with new code and the path will change as well (and so will code).
All you would've needed for a proper solution is adding a new optional property to DiagnosticRecord and making a small change in the extension to pick up this new property or just simply adding a setting in the extension itself only...

[rkeithhill]

Someone make the change to DiagnosticRecord and I'd be happy to plumb this change through PSES and the extension.

[jegannathanmaniganadan]

@bergmeister If this is similar to #1144 ? Then I can submit a PR

[bergmeister]

Yes, you'd add a property to DiagnosticRecord and then translate that property similar to how it was done in that referenced PR.