Run the documentation pipeline when doc/ is edited + various rendering fixes

.github/workflows/documentation.yml

@@ -4,21 +4,18 @@ on:
   push:
     branches: [main, master]
     paths: ['doc/**']
+  pull_request:
+    paths: ['doc/**']
 
 concurrency:
-  group: ${{ github.workflow }}
+  group: ${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: true
 
 jobs:
-  DeployDocs:
-    environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
+  Build:
     runs-on: ubuntu-latest
     permissions:
         contents: read
-        pages: write
-        id-token: write
     steps:
       - name: Checkout actions
         uses: actions/checkout@v4
@@ -35,6 +32,18 @@ jobs:
         with:
           path: doc/site
 
+  DeployDocs:
+    needs: Build
+    if: github.event_name == 'push'
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    permissions:
+        contents: read
+        pages: write
+        id-token: write
+    steps:
       - name: Deploy to GitHub Pages
         id: deployment
         uses: actions/deploy-pages@v4

doc/docs/api-reference/cpp/core-classes/container.md

@@ -1,6 +1,7 @@
 # Container
 
 **Methods**
+
 - `Start()`
 - `Stop(Signal signal, TimeSpan timeout)`
 - `Delete(DeleteContainerOption options)`
@@ -12,6 +13,7 @@
 - `Close()`
 
 **Behavior notes**
+
 - `Start()` automatically sets `WSLC_CONTAINER_START_FLAG_ATTACH` if an init process exists and its output mode is `Event` or `Stream`.
 - `Stop()` converts the timeout to **seconds**, rejects negative values, and rejects values that exceed `uint32_t`.
 - `InitProcess()` throws if the container was not configured with one.

doc/docs/api-reference/cpp/core-classes/process.md

@@ -3,6 +3,7 @@
 `Process` objects are returned by `Container::CreateProcess()` and `Container::InitProcess()`.
 
 **Methods / events**
+
 - `Start()`
 - `Signal(Signal signal)`
 - `GetOutputStream(ProcessOutputHandle outputHandle)`
@@ -16,6 +17,7 @@
 - `Close()`
 
 **Behavior notes**
+
 - `Start()` cannot be called on the init process.
 - `Start()` requires a non-empty `ProcessSettings::CommandLine()`.
 - `GetOutputStream()` requires `ProcessOutputMode::Stream`.

doc/docs/api-reference/cpp/core-classes/session.md

@@ -1,10 +1,12 @@
 # Session
 
 **Constructor**
+
 - `Session(SessionSettings settings)`
   - rejects `nullptr` settings.
 
 **Methods**
+
 - `Start()`
 - `Terminate()`
 - `CreateContainer(ContainerSettings containerSettings)`
@@ -27,6 +29,7 @@
 - `Close()`
 
 **Behavior notes**
+
 - `Start()` is one-shot; calling it twice throws.
 - Most methods call `EnsureStarted()` first.
 - `ImportImage` / `ImportImageAsync` and `LoadImage` / `LoadImageAsync` are path-based only.
@@ -83,18 +86,18 @@ for (auto const& image : images)
 ```
 
 ```cpp
-PullImageOptions pullOptions = ;
+PullImageOptions pullOptions = {};
 auto pullOp = session.PullImageAsync(pullOptions);
 pullOp.Progress([](auto&&, ImageProgress const& p) { /* progress */ });
 co_await pullOp;
 
-PushImageOptions pushOptions = ;
+PushImageOptions pushOptions = {};
 co_await session.PushImageAsync(pushOptions);
 
-TagImageOptions tagOptions = ;
+TagImageOptions tagOptions = {};
 session.TagImage(tagOptions);
 
-VhdOptions vhdOptions = ;
+VhdOptions vhdOptions = {};
 session.CreateVhdVolume(vhdOptions);
 session.DeleteVhdVolume(L"build-cache");
 ```

doc/docs/api-reference/cpp/data-classes/containernamedvolume.md

@@ -3,6 +3,7 @@
 Attaches a named session VHD volume to a container.
 
 **Constructors / properties**
+
 - `ContainerNamedVolume(hstring name, hstring containerPath, bool readOnly)`
 - `Name()` / setter
 - `ContainerPath()` / setter

doc/docs/api-reference/cpp/data-classes/containerportmapping.md

@@ -3,13 +3,15 @@
 Maps a Windows host port to a container port.
 
 **Constructors / properties**
+
 - `ContainerPortMapping(uint16_t windowsPort, uint16_t containerPort, PortProtocol protocol)`
 - `WindowsPort()` / setter
 - `ContainerPort()` / setter
 - `Protocol()` / setter
 - `WindowsAddress()` / setter
 
 **Important notes**
+
 - `WindowsAddress` is implemented.
 - The setter accepts only `Windows::Networking::HostName` values whose type is `Ipv4` or `Ipv6`.
 - `ToStruct()` uses `inet_pton` and stores a real `sockaddr_in` / `sockaddr_in6`.

doc/docs/api-reference/cpp/data-classes/containervolume.md

@@ -3,6 +3,7 @@
 Binds a Windows path into the container.
 
 **Constructors / properties**
+
 - `ContainerVolume(hstring windowsPath, hstring containerPath, bool readOnly)`
 - `WindowsPath()` / setter
 - `ContainerPath()` / setter

doc/docs/api-reference/cpp/data-classes/imageinfo.md

@@ -3,6 +3,7 @@
 Read-only wrapper created from `WslcImageInfo`.
 
 **Properties**
+
 - `Name()` → image name
 - `Sha256()` → 32-byte buffer
 - `Size()` → image size

doc/docs/api-reference/cpp/data-classes/imageprogress.md

@@ -3,6 +3,7 @@
 Progress item reported by image pull/import/load/push operations.
 
 **Properties**
+
 - `Id()`
 - `Status()`
 - `CurrentBytes()`

doc/docs/api-reference/cpp/data-classes/installprogress.md

@@ -3,6 +3,7 @@
 Progress item reported by `WslcService::InstallWithDependenciesAsync()`.
 
 **Properties**
+
 - `Component()`
 - `Progress()`
 - `Total()`

doc/docs/api-reference/cpp/delegates-and-events/processcrashhandler.md

@@ -1,6 +1,7 @@
 # ProcessCrashHandler
 
 Observed use:
+
 - `Session::ProcessCrashed` raises one `ProcessCrashInformation` argument.
 
 ```cpp

doc/docs/api-reference/cpp/delegates-and-events/processexithandler.md

@@ -1,6 +1,7 @@
 # ProcessExitHandler
 
 Observed use:
+
 - `Process::Exited` raises one `int32_t exitCode`.
 
 ```cpp

doc/docs/api-reference/cpp/delegates-and-events/processoutputhandler.md

@@ -1,6 +1,7 @@
 # ProcessOutputHandler
 
 Observed use:
+
 - `Process::OutputReceived` and `Process::ErrorReceived` raise one argument containing raw output bytes.
 - The wrapper forwards a `winrt::array_view<const uint8_t>` produced from the C callback buffer.
 

doc/docs/api-reference/cpp/delegates-and-events/sessionterminationhandler.md

@@ -1,6 +1,7 @@
 # SessionTerminationHandler
 
 Observed use:
+
 - `Session::Terminated` raises one argument: `SessionTerminationReason reason`.
 
 ```cpp

doc/docs/api-reference/cpp/enumerations/component.md

@@ -3,6 +3,7 @@
 `WslcService::GetMissingComponents()` returns a `Component` bitmask.
 
 Underlying values:
+
 - `VirtualMachinePlatform = 1`
 - `WslPackage = 2`
 - `SdkNeedsUpdate = 4`

doc/docs/api-reference/cpp/enumerations/containernetworkingmode.md

@@ -1,10 +1,12 @@
 # ContainerNetworkingMode
 
 `winrt_ContainerSettings.cpp` explicitly validates only:
+
 - `None`
 - `Bridged`
 
 Underlying C values:
+
 - `None = 0`
 - `Bridged = 1`
 

doc/docs/api-reference/cpp/enumerations/containerstate.md

@@ -3,6 +3,7 @@
 `Container::State()` casts directly from `WslcContainerState`.
 
 Underlying C values:
+
 - `Invalid = 0`
 - `Created = 1`
 - `Running = 2`

doc/docs/api-reference/cpp/enumerations/deletecontaineroption.md

@@ -3,6 +3,7 @@
 `Container::Delete()` takes `DeleteContainerOption`.
 
 Underlying values:
+
 - `None = 0`
 - `Force = 1`
 

doc/docs/api-reference/cpp/enumerations/error.md

@@ -1,6 +1,7 @@
 # Error
 
 Underlying HRESULT values:
+
 - `ImageNotFound = -2147219967`
 - `ContainerPrefixAmbiguous = -2147219966`
 - `ContainerNotFound = -2147219965`

doc/docs/api-reference/cpp/enumerations/imageprogressstatus.md

@@ -3,6 +3,7 @@
 `ImageProgress` casts directly from `WslcImageProgressStatus`.
 
 Underlying C values:
+
 - `Unknown = 0`
 - `Pulling = 1`
 - `Waiting = 2`

doc/docs/api-reference/cpp/enumerations/portprotocol.md

@@ -4,6 +4,7 @@
 - The value is passed directly to `WslcContainerPortMapping::protocol`.
 
 Underlying C values:
+
 - `TCP = 0`
 - `UDP = 1`
 

doc/docs/api-reference/cpp/enumerations/processoutputhandle.md

@@ -1,6 +1,7 @@
 # ProcessOutputHandle
 
 `Process::GetOutputStream(ProcessOutputHandle)` accepts these values:
+
 - `StandardOutput = 1`
 - `StandardError = 2`
 

doc/docs/api-reference/cpp/enumerations/processoutputmode.md

@@ -1,11 +1,13 @@
 # ProcessOutputMode
 
 Underlying values:
+
 - `Discard = 0`
 - `Stream = 1`
 - `Event = 2`
 
 Behavior:
+
 - `Discard`: no stdout/stderr events or output streams.
 - `Stream`: `GetOutputStream(...)` can be used.
 - `Event`: stdout/stderr are delivered by callbacks and `OutputReceived` / `ErrorReceived`.

doc/docs/api-reference/cpp/enumerations/processstate.md

@@ -3,6 +3,7 @@
 `Process::State()` casts directly from `WslcProcessState`.
 
 Underlying C values:
+
 - `Unknown = 0`
 - `Running = 1`
 - `Exited = 2`

doc/docs/api-reference/cpp/enumerations/sessionterminationreason.md

@@ -3,6 +3,7 @@
 `Session::OnTerminated` converts `WslcSessionTerminationReason` directly to the WinRT enum.
 
 Underlying C values:
+
 - `Unknown = 0`
 - `Shutdown = 1`
 - `Crashed = 2`

doc/docs/api-reference/cpp/enumerations/signal.md

@@ -3,6 +3,7 @@
 `Container::Stop()` and `Process::Signal()` cast directly to `WslcSignal`.
 
 Underlying values:
+
 - `None = 0`
 - `SIGHUP = 1`
 - `SIGINT = 2`

doc/docs/api-reference/cpp/enumerations/vhdtype.md

@@ -1,6 +1,7 @@
 # VhdType
 
 Underlying values:
+
 - `Dynamic = 0`
 - `Fixed = 1`
 

doc/docs/api-reference/cpp/service-class/wslcservice.md

@@ -3,12 +3,14 @@
 Static entry points over the service-level C API.
 
 **Methods**
+
 - `GetMissingComponents()`
 - `GetVersion()`
 - `InstallWithDependencies()`
 - `InstallWithDependenciesAsync()`
 
 **Behavior notes**
+
 - `GetMissingComponents()` returns a `Component` bitmask.
 - `GetVersion()` returns a `ServiceVersion` constructed from `major`, `minor`, and `revision`.
 - `InstallWithDependencies()` installs dependencies synchronously.

doc/docs/api-reference/cpp/settings-classes/containersettings.md

@@ -1,10 +1,12 @@
 # ContainerSettings
 
 **Constructor**
+
 - `ContainerSettings(hstring imageName)`
   - `imageName` must be non-empty.
 
 **Properties**
+
 - `ImageName()` / setter
 - `Name()` / setter
 - `InitProcess()` / setter
@@ -19,6 +21,7 @@
 - `NamedVolumes()` / setter
 
 **Important notes**
+
 - Collection setters reject `nullptr`.
 - When converting to the C struct, null elements inside the collections are rejected.
 

doc/docs/api-reference/cpp/settings-classes/processsettings.md

@@ -1,12 +1,14 @@
 # ProcessSettings
 
 **Properties**
+
 - `WorkingDirectory()` / setter
 - `CommandLine()` / setter
 - `EnvironmentVariables()` / setter
 - `OutputMode()` / setter
 
 **Important notes**
+
 - `CommandLine(nullptr)` and `EnvironmentVariables(nullptr)` are rejected.
 - `Process::Start()` later requires a **non-empty** `CommandLine()`.
 - `ProcessOutputMode::Event` installs C callbacks; `ProcessOutputMode::Stream` expects stream access; `Discard` is the default.

doc/docs/api-reference/cpp/settings-classes/sessionsettings.md

@@ -1,11 +1,13 @@
 # SessionSettings
 
 **Constructor**
+
 - `SessionSettings(hstring name, hstring storagePath)`
   - `name` must be non-empty.
   - `storagePath` must be non-empty.
 
 **Properties**
+
 - `Name()` / setter
 - `StoragePath()` / setter
 - `CpuCount()` / setter (`0` rejected)

doc/docs/api-reference/cpp/settings-classes/vhdoptions.md

@@ -1,6 +1,7 @@
 # VhdOptions
 
 **Properties**
+
 - `Name()` / setter
 - `Size()` / setter
 - `Type()` / setter