Skip to content

Fix docs generation flow for Pester 6 and regenerate 6.0.0-rc2 docs#384

Merged
nohwnd merged 4 commits into
mainfrom
nohwnd-verbose-telegram
Jun 30, 2026
Merged

Fix docs generation flow for Pester 6 and regenerate 6.0.0-rc2 docs#384
nohwnd merged 4 commits into
mainfrom
nohwnd-verbose-telegram

Conversation

@nohwnd

@nohwnd nohwnd commented Jun 29, 2026

Copy link
Copy Markdown
Member

Why

The Update Pester Docs workflow broke when regenerating docs for 6.0.0-rc2:

Unable to find type [PesterConfiguration]

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.0 Pester.dll can'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:
    • strip the spurious ProgressAction common parameter (SYNTAX blocks + ### -ProgressAction sections) that platyPS emits on 7.4+ (#663);
    • keep the [<CommonParameters>] SYNTAX token and the ### CommonParameters section as platyPS produces them. Because ProgressAction is longer than [<CommonParameters>] and always sits right before it, removing ProgressAction could orphan [<CommonParameters>] on a dangling wrapped line. Format-SyntaxCommonParameters re-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 without ProgressAction (no dangling lines, no horizontal scroll);
    • repair mismatched example code fences (Repair-ExampleFences). rc2's comment-based help embeds Markdown code fences (and a powereshell typo) 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-specific Run.RepoRoot default (eagerly resolved to the generator's git root) with an illustrative C:\MyProject placeholder so no build path leaks into the published docs. (Kept main'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 — preamble Run.Path examples use C:\MyProject\tests; Run.RepoRoot renders as 'C:\MyProject'.
  • Regenerated the command reference + Configuration page for 6.0.0-rc2: adds Should-BeHashtable and 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

  • Regenerated locally on PowerShell 7.5.5 with Pester 6.0.0-rc2: 0 ProgressAction across all command files; [<CommonParameters>] token + ### CommonParameters section present in all 65 command pages; longest SYNTAX line is 110 chars (no horizontal scroll); no machine-path leaks.
  • yarn build passes locally and the Netlify deploy preview is green — the rc2 MDX compiles.
  • Re-dispatched the Update Pester Docs workflow against this branch: succeeds on CI (PS 7.4+) and opens no docs-update PR, confirming the committed docs exactly match what the scripts generate (idempotent, no drift).

nohwnd and others added 4 commits June 29, 2026 23:40
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>
@nohwnd nohwnd merged commit a9ad6a8 into main Jun 30, 2026
4 checks passed
@nohwnd nohwnd deleted the nohwnd-verbose-telegram branch June 30, 2026 07:24
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant