Merge pull request #26000 from l0rd/docs-with-podman

Build documentation in a container on Win arm64

Author: openshift-merge-bot[bot]

build_windows.md

@@ -59,17 +59,19 @@ reloaded. This can also be manually changed by configuring the `PATH`:
 $env:Path += ";C:\Program Files\Go\bin\;C:\Program Files\Git\cmd\"
 ```
 
-### Pandoc
+### Pandoc (optional)
 
 [Pandoc](https://pandoc.org/) is used to generate Podman documentation. It is
-required for building the documentation and the
-[bundle installer](#build-the-installer). It can be avoided when building and
-testing the
-[Podman client for Windows](#build-and-test-the-podman-client-for-windows) or
-[the standalone `podman.msi` installer](#build-and-test-the-standalone-podmanmsi-file).
+used for building the documentation.
 Pandoc can be installed from https://pandoc.org/installing.html. When performing
 the Pandoc installation one, has to choose the option "Install for all users"
 (to put the binaries into "Program Files" directory).
+Alternatively, Podman documentation can be built using a container with the target
+`docs-using-podman` in the `winmake.ps1` script.
+
+```pwsh
+.\winmake docs-using-podman
+```
 
 ### .NET SDK
 
@@ -326,7 +328,7 @@ To build the installation bundle, run the following command:
 .\winmake.ps1 installer
 ```
 
-:information_source: making `podman-remote`, `win-gvproxy`, and `docs` is
+:information_source: making `podman-remote`, `win-gvproxy`, and `docs` (or `docs-using-podman`) is
 required before running this command.
 
 Locate the installer in the `contrib\win-installer` folder (relative to checkout

docs/Containerfile

@@ -0,0 +1,21 @@
+# The resulting image can be used to generate podman-remote documentation.
+#
+# The CMD expects that the podman git repository is bind mounted to /podman.
+# The generated documentation will be copied to ./docs/build/remote/.
+#
+# Example usage:
+#   podman build --build-arg TARGET_OS=windows -t podman-docs-generator $(pwd)/docs
+#   podman run --rm -v $(pwd):/podman podman-docs-generator
+#
+FROM docker.io/golang:latest
+ARG TARGET_OS=windows # valid values: macos, linux, windows
+RUN apt-get update && apt-get install -y pandoc man
+RUN mkdir -p /podman-copy/podman
+ENV TARGET_OS=$TARGET_OS
+WORKDIR /podman-copy/podman
+CMD echo "Copying /podman/ to /podman-copy/. It will take some time but 1) the build will be faster 2) the local bin folder won't be overridden." && \
+    cp -a /podman/ /podman-copy/ && \
+    echo "Generating docs" && make podman-remote-${TARGET_OS}-docs && \
+    echo "Copying generated docs to /podman/" && mkdir -p /podman/docs/build/ && \
+    mkdir -p /podman/docs/build/remote/ && \
+    cp -a /podman-copy/podman/docs/build/remote/${TARGET_OS}/* /podman/docs/build/remote/

winmake.ps1

@@ -96,10 +96,10 @@ function Installer{
     $requiredArtifacts | ForEach-Object {
         if (!(Test-Path -Path $PSItem -PathType Leaf)) {
             Write-Host "$PSItem not found."
-            Write-Host "Make 'podman', 'win-gvproxy' and 'docs' before making the installer:"
+            Write-Host "Make 'podman', 'win-gvproxy' and 'docs' (or 'docs-using-podman') before making the installer:"
             Write-Host "   .\winmake.ps1 podman-remote"
             Write-Host "   .\winmake.ps1 win-gvproxy"
-            Write-Host "   .\winmake.ps1 docs"
+            Write-Host "   .\winmake.ps1 docs or .\winmake.ps1 docs-using-podman"
             Exit 1
         }
     }
@@ -159,6 +159,7 @@ function Documentation{
     # Check that pandoc is installed
     if (!(Get-Command -Name "pandoc" -ErrorAction SilentlyContinue)) {
         Write-Host "Pandoc not found. Pandoc is required to convert the documentation Markdown files into HTML files."
+        Write-Host "Alternatively, use '.\winmake docs-using-podman' to use a container to run pandoc and generate the documentation."
         Exit 1
     }
     # Check that the podman client is built
@@ -170,6 +171,41 @@ function Documentation{
     Run-Command "$PSScriptRoot\docs\make.ps1 $podmanClient"
 }
 
+# DocumentationUsingPodman generates documentation with pandoc running in a container.
+# This is usefult on Windows arm64 where pandoc is not available.
+# It's also useful to generate documentation identical to CI.
+# It requires the podman client to be built and a podman machine running.
+# The whole podman git repository is bind mounted in the container at /podman.
+# The documentation is generated by running the command `make podman-remote-windows-docs`.
+# The generated documentation is stored in the directory docs/build/remote.
+function DocumentationUsingPodman{
+    Write-Host "Generating documentation artifacts"
+    # Check that podman has been built
+    $podmanClient = "${PSScriptRoot}\bin\windows\podman.exe"
+    if (!(Test-Path -Path $podmanClient -PathType Leaf)) {
+        Write-Host "$podmanClient not found. Make 'podman-remote' before 'documentation'."
+        Exit 1
+    }
+    # Check that a podman machine exist
+    $currentMachine = (& ${podmanClient} machine info -f json | ConvertFrom-Json).Host.CurrentMachine
+    if (!$currentMachine) {
+        Write-Host "Podman machine doesn't exist. Initialize and start one before running the validate script."
+        Exit 1
+    }
+    # Check that the podman machine is running
+    $state = (& ${podmanClient} machine info -f json | ConvertFrom-Json).Host.MachineState
+    if ($state -ne "Running") {
+        Write-Host "Podman machine is not running. Start the machine before running the validate script."
+        Exit 1
+    }
+
+    Write-Host "Building the image to generate the documentation"
+    Run-Command "${podmanClient} build --build-arg TARGET_OS=windows -t podman-docs-generator ${PSScriptRoot}/docs"
+
+    Write-Host "Starting the container to run the documentation build"
+    Run-Command "${podmanClient} run -t --rm -v ${PSScriptRoot}:/podman podman-docs-generator"
+}
+
 function Validate{
     $podmanExecutable = "podman"
     $podmanSrcVolumeMount = "${PSScriptRoot}:/go/src/github.com/containers/podman"
@@ -329,6 +365,9 @@ switch ($target) {
     'docs' {
         Documentation
     }
+    'docs-using-podman' {
+        DocumentationUsingPodman
+    }
     'validatepr' {
         Validate
     }
@@ -359,9 +398,12 @@ switch ($target) {
         Write-Host "Example: Run windows installer tests"
         Write-Host " .\winmake installertest hyperv"
         Write-Host
-        Write-Host "Example: Generate the documetation artifacts"
+        Write-Host "Example: Generate the documentation artifacts"
         Write-Host " .\winmake docs"
         Write-Host
+        Write-Host "Example: Generate the documentation artifacts by running pandoc in a container"
+        Write-Host " .\winmake docs-using-podman"
+        Write-Host
         Write-Host "Example: Validate code changes before submitting a PR"
         Write-Host " .\winmake validatepr"
         Write-Host