Fix docs generation flow for Pester 6 and regenerate 6.0.0-rc2 docs#384
Merged
Conversation
Pester 6 ships a .NET 8 assembly and requires PowerShell 7.4+, but the workflow downgraded to 7.3 (to dodge platyPS #663). On 7.3 the net8.0 Pester.dll fails to load, so [PesterConfiguration] is unavailable and the "Update Pester Docs" workflow broke. Run on the runner's default 7.4+ and strip the spurious ProgressAction parameter from the generated MDX instead. - generate-pester-docs.yml: drop the PowerShell 7.3 downgrade step - generate-command-reference.ps1: strip ProgressAction (platyPS #663) post-gen - generate-pesterconfiguration-docs.ps1: null-safe default/type handling and replace the machine-specific Run.RepoRoot default with an illustrative C:\MyProject placeholder - Regenerate command reference and Configuration page for 6.0.0-rc2 (adds Should-BeHashtable and the new rc2 config options) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Integrate main's v6 docs updates (PRs #379-#383, incl. MDX-escaping in the config generator and new usage pages) with this branch's docs-generation fix. Re-applied on top of the merge: - Keep Run.RepoRoot rendered as the illustrative placeholder C:\MyProject (and preamble Run.Path examples as C:\MyProject\tests). - Regenerate command reference on PowerShell 7.4+ and drop both the spurious ProgressAction common parameter and the [<CommonParameters>] SYNTAX token. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Pester rc2's comment-based help embeds Markdown code fences (and a
'powereshell' typo) inside its .EXAMPLE blocks. PlatyPS double-wraps these
into mismatched fences, which MDX 3 mispairs - it then tries to parse an
example's PowerShell `@{ ... }` as a JSX expression and fails the Docusaurus
build ("Could not parse expression with acorn").
Add a Repair-ExampleFences post-processing pass to generate-command-reference.ps1
that normalizes fences within the EXAMPLES section so every example renders as a
single well-formed powershell code block, and regenerate the two affected files
(Should-BeEquivalent, Set-ItResult).
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Restore the '[<CommonParameters>]' SYNTAX token and the '### CommonParameters' section that PlatyPS emits, instead of dropping them. Removing the spurious ProgressAction token (PlatyPS #663 on PowerShell 7.4+) can leave the token orphaned on a wrapped continuation line, so Format-SyntaxCommonParameters re-wraps it onto its own line only when the SYNTAX line would exceed PlatyPS's wrap width (~110 chars), matching the layout PlatyPS produces natively without ProgressAction. Regenerated all command docs for 6.0.0-rc2. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
The Update Pester Docs workflow broke when regenerating docs for
6.0.0-rc2:Root cause: Pester 6 ships a .NET 8 assembly and requires PowerShell 7.4+, but the workflow deliberately downgraded to 7.3 (to dodge platyPS #663). On 7.3 the
net8.0Pester.dllcan't load, so[PesterConfiguration]never registers and generation fails. The two workarounds were mutually exclusive.Regenerating on 7.4+ then surfaced two further issues that broke the Docusaurus (MDX 3) build, both fixed here.
What
generate-pester-docs.yml— drop the PowerShell 7.3 downgrade step; run on the runner's default 7.4+.generate-command-reference.ps1— post-process the generated MDX to:ProgressActioncommon parameter (SYNTAX blocks +### -ProgressActionsections) that platyPS emits on 7.4+ (#663);[<CommonParameters>]SYNTAX token and the### CommonParameterssection as platyPS produces them. BecauseProgressActionis longer than[<CommonParameters>]and always sits right before it, removingProgressActioncould orphan[<CommonParameters>]on a dangling wrapped line.Format-SyntaxCommonParametersre-wraps it onto its own line only when the SYNTAX line would exceed platyPS's wrap width (~110 chars), reproducing the layout platyPS emits natively withoutProgressAction(no dangling lines, no horizontal scroll);Repair-ExampleFences). rc2's comment-based help embeds Markdown code fences (and apowereshelltypo) inside.EXAMPLE; platyPS double-wraps them into mismatched fences, so MDX 3 mispaired them and tried to parse an example's@{ ... }as a JSX expression →Could not parse expression with acorn. The pass normalizes each example into a single well-formed ```powershell block.generate-pesterconfiguration-docs.ps1— replace the machine-specificRun.RepoRootdefault (eagerly resolved to the generator's git root) with an illustrativeC:\MyProjectplaceholder so no build path leaks into the published docs. (Keptmain's MDX-escaping + null-safety from Update v6 docs from 6.0.0 release notes #379/Claim PowerShell 7.4+ support instead of 7.2+ #381.)docs/usage/configuration.mdx— preambleRun.Pathexamples useC:\MyProject\tests;Run.RepoRootrenders as'C:\MyProject'.6.0.0-rc2: addsShould-BeHashtableand the new rc2 config options (Run.Parallel,Run.BeforeContainer,Run.ParallelThrottleLimit,Run.RepoRoot,CodeCoverage.ReportRoot,Debug.ShowStartMarkers).This branch also merges current
main(PRs #379–#383, incl. the MDX-escaping config-generator changes and new usage pages).Verification
6.0.0-rc2:0ProgressActionacross all command files;[<CommonParameters>]token +### CommonParameterssection present in all 65 command pages; longest SYNTAX line is 110 chars (no horizontal scroll); no machine-path leaks.yarn buildpasses locally and the Netlify deploy preview is green — the rc2 MDX compiles.docs-updatePR, confirming the committed docs exactly match what the scripts generate (idempotent, no drift).