Migrate to Alt3.Docusaurus.PowerShell v2 and update all docs to latest - #418
Migrate to Alt3.Docusaurus.PowerShell v2 and update all docs to latest#418fflaten wants to merge 20 commits into
Conversation
fflaten
changed the title
Co-authored-by: Frode Flaten <3436158+fflaten@users.noreply.github.com>
Co-authored-by: Frode Flaten <3436158+fflaten@users.noreply.github.com>
Update v5 docs to Pester v5.9.0
Co-authored-by: Frode Flaten <3436158+fflaten@users.noreply.github.com>
Update v4 docs to Pester v4.10.1
fflaten
changed the title
* Update generated docs to 6.1.0 Regenerated the command reference and the configuration table against Pester 6.1.0. Adds the New-ShouldAssertion page, which also clears the two broken links that #440 left behind. Picks up -NormalizeLineEnding on Should-BeString and Should-NotBeString, the Should-Throw wildcard hint, and in the configuration table Run.Shuffle, Run.ShuffleSeed, Output.ShowTags and Mock.Global. Drops the removed Run.BeforeContainer row. Generated with -DocusaurusVersion 1.0.37. Alt3.Docusaurus.PowerShell 2.0.0 is out now, and the unpinned script picks it up and then fails on a YamlDotNet assembly conflict with PlatyPS, so it needs pinning until #418 lands. 🤖 * Update generated v5 docs to 5.9.1 The v5 command reference and configuration section were still generated from 5.8.0. 5.9.1 changed no help text, so this is only the version stamp, but it keeps the versioned docs honest about which release they describe. 🤖
|
The 92 conflicts here are all generated output, 65 in Only 6 files on this branch are real source: I can do the regeneration if you want, just say so. 🤖 |
|
Will rebuild and force push. Brb |
Most conflicts were generated command pages. Main regenerated them for 6.1.0 in pester#441 with the old generator while this branch has them from the v2 generator at the same version, so resolved by keeping this branch and dropping the old-generator output. Two real resolutions: - versioned_docs/version-v5/usage/configuration.mdx, that section is generated separately and was still on 5.9.0 here, took 5.9.1 from main. - versioned_sidebars/version-v4-sidebars.json, main restructured the whole v4 sidebar while this branch only changed one id in the old structure. Kept main structure and re-applied the id, commands/Add-ShouldOperator, to match the docId the v2 generator writes for Add-AssertionOperator. Without it the build fails with "Invalid sidebar file". Verified: yarn build passes. 🤖
|
Merged main into your branch, it is green now. Most of the conflicts were the generated command pages. Main regenerated them for 6.1.0 in #441 with the old generator, so I kept your v2 output and dropped main's. Two needed a real fix:
One I left alone: 🤖 |
Invoke-Gherkin in Pester 4.10.1 puts two entries in one .LINK block
.LINK
Invoke-Pester
https://kevinmarquette.github.io/2017-03-17-...
and PlatyPS v2 renders the whole block as one link with an empty url, so
both entries end up dead. The old generator dropped the second line instead.
Repair it in post-processing, one entry per line, and expand a bare command
name to its pester.dev url so it matches the urls the other .LINK entries
already use. Invoke-Gherkin is the only page affected today, the fix is
generic so it also covers any help written the same way later.
Verified: pnpm build passes and no longer warns about an empty link url.
🤖
|
Merged main again to pick up pnpm, and fixed the empty link I mentioned above instead of leaving it to you. The source is worse than it looked. Invoke-Gherkin in 4.10.1 puts two entries in one PlatyPS v2 renders the whole block as one link with an empty url, so both entries are dead, and the old generator silently dropped the second line. The page was losing two links, not one. Repaired it in post-processing, one entry per line, and a bare command name expands to its pester.dev url so it matches what the other One thing you should know before looking at CI here: main does not build right now, and it is not this branch. #421 and #435 are both fine alone, but the tutorial components import 🤖 |
| function Repair-RelatedLinks { | ||
| <# | ||
| A .LINK block that holds more than one entry is rendered as a single link | ||
| with an empty url, for example | ||
|
|
||
| - [Invoke-Pester | ||
| https://kevinmarquette.github.io/2017-03-17-...]() | ||
|
|
||
| Invoke-Gherkin in Pester 4.10.1 writes its help that way. Split such a link | ||
| into one entry per line, and expand a bare command name to its pester.dev url | ||
| so it matches the urls the other .LINK entries already use. | ||
| #> | ||
| param([string] $Content) | ||
|
|
||
| $eol = if ($Content -match "`r`n") { "`r`n" } else { "`n" } | ||
| $lines = $Content -split "`r?`n" | ||
| $out = [System.Collections.Generic.List[string]]::new() | ||
| foreach ($line in $lines) { | ||
| if ($line.Length -gt $MaxWidth -and $line -match '\S[ ]\[<CommonParameters>\][ ]*$') { | ||
| $head = $line -replace '[ ]*\[<CommonParameters>\][ ]*$', '' | ||
| $out.Add($head) | ||
| $out.Add(' [<CommonParameters>]') | ||
| } | ||
| else { | ||
| $out.Add($line) | ||
|
|
||
| [regex]::Replace( | ||
| $Content, | ||
| '(?m)^-[ ]\[([\s\S]*?)\]\(\)[ ]*$', | ||
| { | ||
| param($m) | ||
| $entries = $m.Groups[1].Value -split "`r?`n" | | ||
| ForEach-Object { $_.Trim() } | | ||
| Where-Object { $_ } | ||
|
|
||
| ($entries | ForEach-Object { | ||
| $target = if ($_ -match '^https?://') { $_ } else { "https://pester.dev/docs/commands/$_" } | ||
| "- [$target]($target)" | ||
| }) -join $eol | ||
| } | ||
| } | ||
| return ($out -join $eol) | ||
| ) |
There was a problem hiding this comment.
This is overengineered in my opinion. v4 is static, so fix Invoke-Gherkin page manually. Future versions should be fixed in pester-repo as a command help syntax bug - not repaired here.
|
Thanks for fixing the conflicts btw :) LGTM besides the comment above - if you agree. Note: There is currently a platyPS bug that affects the two Assert-* commands in v5 docs. See PowerShell/platyPS#860 . Manually fixed the output in this PR, but should probably add the missing descriptions in Pester v5 comment help in case we do a new v5 patch release. |
2 participants
Update Alt3.Docusarus.PowerShell 2.0 with Microsoft.PowerShell.PlatyPS 1.0
Update meta description on command reference pages to include synopsis for improved information in social media sharing, search results etc.
Updates all command reference to latest GA-releases
Uses rel/4.x.x and rel/5.x.x branch links for contributions to old versions
Removes unused template logo assets
Related: alt3/Docusaurus.Powershell#241