Pester: Example 1 of Descibe doesn't correctly format

[iRon7]

Document: https://pester-docs.netlify.app/docs/commands/Describe

Example 1 doesn't correctly format: (probably not completely set as code):

[nohwnd]

Thanks. Will fix that in https://github.com/pester/Pester/blob/v5.0/src/functions/Describe.ps1

[nohwnd]

@iRon7 moved here.

[fflaten]

@nohwnd I don't think the new PR is necessary unless you wanted to cindent it. Pester.dev hasn't been updated to reflect the updates I made for 5.1, so the codeblock should work when @bravo-kernel or someone reruns the generation of Command Reference based on 5.1 release 👍

[bravo-kernel]

It would be nice if I could get some from you PS gurus to help improving/simplifying that script so it e.g. uses a specific pester version or something. Pointers, suggestions, etc welcome.

[fflaten]

@bravo-kernel are you thinking about generate-command-reference.ps1 ? It has 5.0.3 hard-coded in the #require-line atm. Maybe create an issue in docs-repo with a bit more details, then we can find a solution. Maybe even get a action running to create a docs PR with updated command reference at release-tag?

[bravo-kernel]

Exactly, that script and ideally in two steps:

1. Make it easier to specify a Pester version in that script. Polish it, feel free to PR

2. Create a CI/CD pipeline using that improved script. I could do that.

[nohwnd]

Ah okay, I am a bit lost about how we generate the help here. I know we talked about running some pipeline automatically in the future and that bravo-kernel documented it. I probably just need to go and read that.

How about this:

• we move the script into pester/Pester repo. And add it to the main pipeline.
• On every build of v5 branch we generate the help.
• compare if there are any changes*
• when there are changes we make a PR to pester/docs https://github.com/shayki5/azure-devops-create-pr-task

*How do we detect if there are any changes? I don't know. But I propose this:
Split all helps into .psh1 file and insert them back into their functions using a directive that is picked up during build.ps1 (like we do with the conditional inlining).

This would make it easy to detect changes as there would be a change in .psh1 file. And it would also remove the help from the .ps1 file, which makes scrolling through the file soo much less annoying.

[bravo-kernel]

OK, let's try to keep this as simple as possible.

File changes

The generate-command-reference.ps1 script:

• only generates the .mdx files and the docusaurus.sidebar.js file found in this docs\command directory
  
  
  
  • then replaces the existing content of above folder with the newly generated mdx files
  
  
  • only mdx file changes will appear in the PR
  
  

The process

We already have a working process, it just needs some fine tuning IMO.

1. Do not move generate script out of the pester/docs repo
2. Update the generate script so it no longer uses a fixed Pester version but either:
   
   
   
   • uses latest Pester version (by default)
   
   
   • uses a specified Pester version if parameter is given (e.g. -PesterVersion)
   
   
3. Use that updated script to implement CI/CD

CI/CD

A solution was discussed earlier, something like:

1. pester/pester repo creates a new release
2. pester/pester release triggers a github action in the pester/docs repo
3. that pester/docs action uses the generate script to:
   
   
   
   • regenerate the mdx files using LATEST pester version
   
   
   • create a PR with the mdx file changes
   
   

This way everything stays as it is now with wesbite-previews etc. and.. no need to move pester-docs-related logic into the pester/pester repo.

Does that make sense?

[fflaten]

I like it. How fast is the Pester-version available in PSGallery compared to when @nohwnd creates the release-tag? ⚡
Can we rely on the it being available or should we build module from source?

I'm not very experienced with CI, but it looks like we can use https://docs.github.com/en/free-pro-team@latest/rest/reference/repos#create-a-repository-dispatch-event on release to trigger a workflow in pester/docs and passing it the release-tag using client_payload. Then pester/docs workflow can use the provided release-tag to checkout the release from pester-repo, build it, generate docs using script and submit a PR for the diffs (e.g. using https://github.com/marketplace/actions/create-pull-request).

Ignore the fact that I used Github Actions. No preferences here, was just used for example 🙂

[nohwnd]

@fflaten I release it "manually" and I commit, tag, build packages and push them, then push tag, then publish release notes. So unless I do it wrong the package is always in gallery before the tag is in the repo.

[bravo-kernel]

Great, looks like we're all on the same page here.

IMO we should start with making the module-versions in that generate script configurable (my initial, and now last, ask for help there). Once that is done I will do the CI part on the pester/docs side, I already have it running so should be easy.

[nohwnd]

@bravo-kernel let me do that.

[nohwnd]

There is an error in the Should code that throws on Get-Command should -Syntax. Will have to add a null check and release this as a preview in 5.1.1-beta1. There is also JSON warning about reaching the maximum depth.

If you want to try it in the meantime you can fix the error above by changing this in Pester.psm1 on line 7171 (in version 5.1):

        $myLine = # we can use $myInvocation.Line to get the surrounding context
            $MyInvocation.Line.Substring($MyInvocation.OffsetInLine - 1)

to this:

        # we can use $myInvocation.Line to get the surrounding context
        $myLine = if ($MyInvocation.Line -and ($MyInvocation.OffsetInLine - 1) -ge 0) {
            $MyInvocation.Line.Substring($MyInvocation.OffsetInLine - 1)
        }

[nohwnd]

https://github.com/pester/docs/pull/77 here is my PR, I only did the minimum amount of work needed, and kept the parameter non-mandatory to make it easy to run locally. if you have different requirements, please let me know :)

[bravo-kernel]

@nohwnd you are correct. I noticed that the regex responsible for grabbing the code blocks (currently) does not support those inline # characters. IIRC there is another example that uses a lot of those as well and.. does not render properly either.

I will try and find a root fix for that in Docusaurus.Powershell when I find some time. Should be possible.

[fflaten]

OP issue fixed in the updated command ref published in pester/docs#78

[nohwnd]

kk. closing this, should we move the https://github.com/pester/Pester/issues/1798#issuecomment-737134366 into a new issue pester/docs?

[bravo-kernel]

Yes we should. I will create it right now and point back to here.

[nohwnd]

@bravo-kernel okay, I could have just referenced this in new issue (and you probably could as well, there is an option for it in the ... menu. Unless you did it that way :) )

[bravo-kernel]

Oh, please do then, for me it will be all manual work. Thanks !!