From 8fd4c47dfd2b20de43fa021f516c3d900037ab90 Mon Sep 17 00:00:00 2001 From: Gunjan Vyas Date: Wed, 22 Jul 2026 17:50:43 +0530 Subject: [PATCH 1/2] docs: fix make.ps1 hanging when Out-String wraps help on narrow consoles Out-String breaks long help lines on smaller consoles (such as CI runners), so command discovery mis-parses wrapped description text as subcommands and docs can recurse forever. Parse as remote-docs.sh Signed-off-by: Gunjan Vyas --- docs/make.ps1 | 53 +++++++++++++++++++++++++++++++++------------------ 1 file changed, 34 insertions(+), 19 deletions(-) diff --git a/docs/make.ps1 b/docs/make.ps1 index 27289aae7f..b452c2d891 100644 --- a/docs/make.ps1 +++ b/docs/make.ps1 @@ -14,32 +14,47 @@ function Get-Podman-Commands-List{ Write-Host "Retrieving the list of ""podman"" commands." } + $helpLines = @(Invoke-Expression "$podmanClient $podmanHelpCommand") + # Retrieve the list of subcommands of $command # e.g. "podman help machine" returns the list of # "podman machine" subcommands: info, init, etc... $subCommands = @() - $subCommands = Invoke-Expression "$podmanClient $podmanHelpCommand" | - Select-String -Pattern "^\s*Available Commands:" -Context 0, 1000 | Out-String -Stream | - Select-String -Pattern "^\s+$" -Context 1000, 0 | Out-String -Stream | - Select-String -Pattern ">\s*Available Commands:|^>\s*$|^\s*$" -NotMatch | Out-String -Stream | - ForEach-Object { $_ -replace '^\s*(\w+)\s+.*$', '$1' } | Where-Object { $_ -ne "" } - - if ($command) { - $subCommands = $subCommands | ForEach-Object { "$command $_" } - } - - # Recursively get the list of sub-subcommands for each subcommand - foreach ($subCommand in $subCommands) { - - $subSubCommands = @() - $subSubCommands = Get-Podman-Commands-List -podmanClient "$podmanClient" -command "${subCommand}" - - if ($subSubCommands) { - $subCommands += $subSubCommands + $inCommands = $false + foreach ($line in $helpLines) { + if ($line -match "^\s*Available Commands:\s*$") { + $inCommands = $true + continue + } + # end of commands list + if ($inCommands -and $line -match '^\s*Options:\s*$') { + break + } + if (!$inCommands) { + continue + } + # add command to list + $name = ($line.Trim() -Split '\s+')[0] + if ($name -and $name -ne 'help') { + $subCommands += $name } } - return $subCommands + if ($command) { + $subCommands = @($subCommands | ForEach-Object { "$command $_" }) + } else { + $subCommands = @($subCommands) + } + + $allCommands = @($subCommands) + foreach ($subCommand in $subCommands) { + $subSubCommands = @(Get-Podman-Commands-List -podmanClient "$podmanClient" -command "${subCommand}") + if ($subSubCommands) { + $allCommands += $subSubCommands + } + } + + return $allCommands } function Build-Podman-For-Windows-HTML-Page{ From f03f196acc3298550d1c6982df9765d08674c458 Mon Sep 17 00:00:00 2001 From: Gunjan Vyas Date: Fri, 31 Jul 2026 13:47:44 +0530 Subject: [PATCH 2/2] docs: expand @@option includes and rename podman-remote.html in make.ps1 Run markdown-preprocess before pandoc (same as make docs), prefer generated .md over .md.in, and rename podman-remote.html to podman.html like remote-docs.sh so Windows winmake docs match the Linux path. Assisted-by: Cursor Signed-off-by: Gunjan Vyas --- docs/make.ps1 | 54 +++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 48 insertions(+), 6 deletions(-) diff --git a/docs/make.ps1 b/docs/make.ps1 index b452c2d891..0c7d8895e9 100644 --- a/docs/make.ps1 +++ b/docs/make.ps1 @@ -57,6 +57,22 @@ function Get-Podman-Commands-List{ return $allCommands } +function Invoke-Markdown-Preprocess{ + $python = Get-Command -Name 'python' -ErrorAction SilentlyContinue + + if (!$python) { + Write-Host 'Python not found. Python is required to expand @@option includes in the markdown sources.' + Exit 1 + } + + Write-Host "Expanding @@option includes in markdown sources (using $($python.Source))..." + & $python.Source "$PSScriptRoot\..\hack\markdown-preprocess" + if ($LASTEXITCODE -ne 0) { + Write-Host 'markdown-preprocess failed.' + Exit 1 + } +} + function Build-Podman-For-Windows-HTML-Page{ $srcFolder = "$PSScriptRoot\tutorials" $srcFile = "$srcFolder\podman-for-windows.md" @@ -86,6 +102,26 @@ function Build-Podman-Remote-HTML-Page{ } } +# Rename podman-remote.html to podman.html to match remote-docs.sh +function Rename-Podman-Remote-HTML{ + $src = "$PSScriptRoot\build\remote\podman-remote.html" + $dst = "$PSScriptRoot\build\remote\podman.html" + if (!(Test-Path -Path $src -PathType Leaf)) { + return + } + + $content = Get-Content -Raw -Path $src + + $content = $content -creplace 'Podman\*-remote', 'Podman for Windows' + $content = $content -creplace 'podman\*-remote', 'podman' + $content = $content -creplace 'Podman-remote', 'Podman for Windows' + $content = $content -creplace 'podman-remote', 'podman' + $content = $content -creplace 'A remote CLI for Podman: ', '' + + Set-Content -Path $dst -Value $content -NoNewline + Remove-Item -Path $src +} + function Find-Podman-Command-Markdown-File{ param ( [string]$command @@ -96,10 +132,11 @@ function Find-Podman-Command-Markdown-File{ $srcFileMd = "$markdownFolder\podman-$command.1.md" $linkFile = "$markdownFolder\links\podman-$command.1" - if (Test-Path -Path $srcFileMdIn -PathType Leaf) { - return $srcFileMdIn - } elseif (Test-Path -Path $srcFileMd -PathType Leaf) { + # Use the already-preprocessed .md file over the raw .md.in template + if (Test-Path -Path $srcFileMd -PathType Leaf) { return $srcFileMd + } elseif (Test-Path -Path $srcFileMdIn -PathType Leaf) { + return $srcFileMdIn } elseif (Test-Path -Path $linkFile -PathType Leaf) { # In $linkFile there is a link to a markdown file $srcFile = Get-Content -Path $linkFile @@ -108,10 +145,10 @@ function Find-Podman-Command-Markdown-File{ $srcFile = $srcFile -replace ".so man1/", "" $srcFileMdIn = "$markdownFolder\$srcFile.md.in" $srcFileMd = "$markdownFolder\$srcFile.md" - if (Test-Path -Path "$srcFileMdIn" -PathType Leaf) { - return "$srcFileMdIn" - } elseif (Test-Path -Path $srcFileMd -PathType Leaf) { + if (Test-Path -Path $srcFileMd -PathType Leaf) { return "$srcFileMd" + } elseif (Test-Path -Path "$srcFileMdIn" -PathType Leaf) { + return "$srcFileMdIn" } } return $null @@ -139,11 +176,16 @@ function Build-Podman-Command-HTML-Page{ Write-Host "done." } +# Expand @@option includes in the markdown sources +Invoke-Markdown-Preprocess + # Generate podman-for-windows.html Build-Podman-For-Windows-HTML-Page # Generate podman-remote*.html Build-Podman-Remote-HTML-Page +# Rename the generated podman-remote*.html +Rename-Podman-Remote-HTML # Get the list of podman commands on Windows if ($args[1]) {