Implement mechanism to keep auto-generated Command Reference in-sync

[bravo-kernel]

All pages in the Command Reference are auto-generated using the Alt3.Docusaurus.Powershell module.

Because it uses the Get-Help documentation produced by Pester as input, it is important to implement some sort of mechanism to keep the pages in-sync with the Pester module releases. One idea talked about creating some sort of "webhook" that triggers this repo once a new Pester version is released.

Good to Know

Powershell used to generate the current command reference pages:

$pesterArgs = @{
    Module = "Pester"
    DocsFolder = "docs"
    SideBar = "commands"
    Exclude = @(
      "Get-MockDynamicParameter"
      "Invoke-Mock"
      "SafeGetCommand"
      "Set-DynamicParameterVariable"
    )
    MetaDescription = 'Help page for the Powershell Pester "%1" command'
    MetaKeywords = @(
        "Powershell"
        "Pester"
        "Help"
        "Documentation"
    )
    EditUrl = 'null' # prevents `Edit this Page` button
    AppendMarkdown = "## EDIT THIS PAGE`n`nThis page was auto-generated using Pester's comment based help. To edit the content of this page, change the corresponding help in the [pester/Pester](https://github.com/pester/pester) repository. See our [contribution guide](https://github.com/pester/docs#contributing) for more information."
}

New-DocusaurusHelp @pesterArgs -Verbose

[bravo-kernel]

Do not feel obliged @glennsarti but since you were in the original discussion I thought I'd send you an update. This can be started.

[glennsarti]

Thanks @bravo-kernel

[glennsarti]

Actually, that raised a question about which versions should be available. @nohwnd

e.g. Latest 4.x and 5.x ?

[bravo-kernel]

Consensus was to start with v4 first. We will then use that version to clone a v5 later in the process.

[glennsarti]

👍 Fair enough.

[bravo-kernel]

Please be aware that you have to use the latest Pester (master) sources or the command reference will not render properly. If you have any questions please let me know.

[bravo-kernel]

@glennsarti not trying to rush you here but are you intending to implement this? If so I will assign the ticket to you (to prevent double work)

[glennsarti]

For now I can't due to workload and family stuff. Up for grabs!

[glennsarti]

One comment. Because the intent here is to raise commits/PRs for docs updates, there needs to be a service account/bot account within github so it can make those commits. To the best of my knowledge there is no such account and that should be maintained, probably, by @nohwnd

[bravo-kernel]

Closing for two reasons:

1. We now have a very effictive script to actualize the docs: Adds -SkipModuleImport to generate-command-reference script #213 (comment)
2. We came to the conclusion that manual updating would be preferred

[fflaten]

We came to the conclusion that manual updating would be preferred

👍 At least until GitHub supports repo-scoped PAT. Then we could trigger workflow on release in Pester-repo which could clone, build and generate docs.