@samitouri / QOSAMI-WSL-1 / commits / 901cb9c1

Run the documentation pipeline when doc/ is edited + various rendering fixes (#40931)

* Run the documentation pipeline when doc/ is edited + various rendering fixes * Fix inverted condition

Blue committed Jun 28, 2026 at 06:43 UTC 901cb9c13456977fcc0e6aef693194cf2ba46267
40 files changed +71 -11
.github/workflows/documentation.yml
+16 -7
@@ -4,21 +4,18 @@ on:
4 push:
5 branches: [main, master]
6 paths: ['doc/**']
7 + pull_request:
8 + paths: ['doc/**']
9
10 concurrency:
9 - group: ${{ github.workflow }}
11 + group: ${{ github.workflow }}-${{ github.ref }}
12 cancel-in-progress: true
13
14 jobs:
13 - DeployDocs:
14 - environment:
15 - name: github-pages
16 - url: ${{ steps.deployment.outputs.page_url }}
15 + Build:
16 runs-on: ubuntu-latest
17 permissions:
18 contents: read
20 - pages: write
21 - id-token: write
19 steps:
20 - name: Checkout actions
21 uses: actions/checkout@v4
@@ -35,6 +32,18 @@ jobs:
32 with:
33 path: doc/site
34
35 + DeployDocs:
36 + needs: Build
37 + if: github.event_name == 'push'
38 + environment:
39 + name: github-pages
40 + url: ${{ steps.deployment.outputs.page_url }}
41 + runs-on: ubuntu-latest
42 + permissions:
43 + contents: read
44 + pages: write
45 + id-token: write
46 + steps:
47 - name: Deploy to GitHub Pages
48 id: deployment
49 uses: actions/deploy-pages@v4
doc/docs/api-reference/cpp/core-classes/container.md
+2
@@ -1,6 +1,7 @@
1 # Container
2
3 **Methods**
4 +
5 - `Start()`
6 - `Stop(Signal signal, TimeSpan timeout)`
7 - `Delete(DeleteContainerOption options)`
@@ -12,6 +13,7 @@
13 - `Close()`
14
15 **Behavior notes**
16 +
17 - `Start()` automatically sets `WSLC_CONTAINER_START_FLAG_ATTACH` if an init process exists and its output mode is `Event` or `Stream`.
18 - `Stop()` converts the timeout to **seconds**, rejects negative values, and rejects values that exceed `uint32_t`.
19 - `InitProcess()` throws if the container was not configured with one.
doc/docs/api-reference/cpp/core-classes/process.md
+2
@@ -3,6 +3,7 @@
3 `Process` objects are returned by `Container::CreateProcess()` and `Container::InitProcess()`.
4
5 **Methods / events**
6 +
7 - `Start()`
8 - `Signal(Signal signal)`
9 - `GetOutputStream(ProcessOutputHandle outputHandle)`
@@ -16,6 +17,7 @@
17 - `Close()`
18
19 **Behavior notes**
20 +
21 - `Start()` cannot be called on the init process.
22 - `Start()` requires a non-empty `ProcessSettings::CommandLine()`.
23 - `GetOutputStream()` requires `ProcessOutputMode::Stream`.
doc/docs/api-reference/cpp/core-classes/session.md
+7 -4
@@ -1,10 +1,12 @@
1 # Session
2
3 **Constructor**
4 +
5 - `Session(SessionSettings settings)`
6 - rejects `nullptr` settings.
7
8 **Methods**
9 +
10 - `Start()`
11 - `Terminate()`
12 - `CreateContainer(ContainerSettings containerSettings)`
@@ -27,6 +29,7 @@
29 - `Close()`
30
31 **Behavior notes**
32 +
33 - `Start()` is one-shot; calling it twice throws.
34 - Most methods call `EnsureStarted()` first.
35 - `ImportImage` / `ImportImageAsync` and `LoadImage` / `LoadImageAsync` are path-based only.
@@ -83,18 +86,18 @@ for (auto const& image : images)
86 ```
87
88 ```cpp
86 -PullImageOptions pullOptions = ;
89 +PullImageOptions pullOptions = {};
90 auto pullOp = session.PullImageAsync(pullOptions);
91 pullOp.Progress([](auto&&, ImageProgress const& p) { /* progress */ });
92 co_await pullOp;
93
91 -PushImageOptions pushOptions = ;
94 +PushImageOptions pushOptions = {};
95 co_await session.PushImageAsync(pushOptions);
96
94 -TagImageOptions tagOptions = ;
97 +TagImageOptions tagOptions = {};
98 session.TagImage(tagOptions);
99
97 -VhdOptions vhdOptions = ;
100 +VhdOptions vhdOptions = {};
101 session.CreateVhdVolume(vhdOptions);
102 session.DeleteVhdVolume(L"build-cache");
103 ```
doc/docs/api-reference/cpp/data-classes/containernamedvolume.md
+1
@@ -3,6 +3,7 @@
3 Attaches a named session VHD volume to a container.
4
5 **Constructors / properties**
6 +
7 - `ContainerNamedVolume(hstring name, hstring containerPath, bool readOnly)`
8 - `Name()` / setter
9 - `ContainerPath()` / setter
doc/docs/api-reference/cpp/data-classes/containerportmapping.md
+2
@@ -3,6 +3,7 @@
3 Maps a Windows host port to a container port.
4
5 **Constructors / properties**
6 +
7 - `ContainerPortMapping(uint16_t windowsPort, uint16_t containerPort, PortProtocol protocol)`
8 - `WindowsPort()` / setter
9 - `ContainerPort()` / setter
@@ -10,6 +11,7 @@ Maps a Windows host port to a container port.
11 - `WindowsAddress()` / setter
12
13 **Important notes**
14 +
15 - `WindowsAddress` is implemented.
16 - The setter accepts only `Windows::Networking::HostName` values whose type is `Ipv4` or `Ipv6`.
17 - `ToStruct()` uses `inet_pton` and stores a real `sockaddr_in` / `sockaddr_in6`.
doc/docs/api-reference/cpp/data-classes/containervolume.md
+1
@@ -3,6 +3,7 @@
3 Binds a Windows path into the container.
4
5 **Constructors / properties**
6 +
7 - `ContainerVolume(hstring windowsPath, hstring containerPath, bool readOnly)`
8 - `WindowsPath()` / setter
9 - `ContainerPath()` / setter
doc/docs/api-reference/cpp/data-classes/imageinfo.md
+1
@@ -3,6 +3,7 @@
3 Read-only wrapper created from `WslcImageInfo`.
4
5 **Properties**
6 +
7 - `Name()` → image name
8 - `Sha256()` → 32-byte buffer
9 - `Size()` → image size
doc/docs/api-reference/cpp/data-classes/imageprogress.md
+1
@@ -3,6 +3,7 @@
3 Progress item reported by image pull/import/load/push operations.
4
5 **Properties**
6 +
7 - `Id()`
8 - `Status()`
9 - `CurrentBytes()`
doc/docs/api-reference/cpp/data-classes/installprogress.md
+1
@@ -3,6 +3,7 @@
3 Progress item reported by `WslcService::InstallWithDependenciesAsync()`.
4
5 **Properties**
6 +
7 - `Component()`
8 - `Progress()`
9 - `Total()`
doc/docs/api-reference/cpp/delegates-and-events/processcrashhandler.md
+1
@@ -1,6 +1,7 @@
1 # ProcessCrashHandler
2
3 Observed use:
4 +
5 - `Session::ProcessCrashed` raises one `ProcessCrashInformation` argument.
6
7 ```cpp
doc/docs/api-reference/cpp/delegates-and-events/processexithandler.md
+1
@@ -1,6 +1,7 @@
1 # ProcessExitHandler
2
3 Observed use:
4 +
5 - `Process::Exited` raises one `int32_t exitCode`.
6
7 ```cpp
doc/docs/api-reference/cpp/delegates-and-events/processoutputhandler.md
+1
@@ -1,6 +1,7 @@
1 # ProcessOutputHandler
2
3 Observed use:
4 +
5 - `Process::OutputReceived` and `Process::ErrorReceived` raise one argument containing raw output bytes.
6 - The wrapper forwards a `winrt::array_view<const uint8_t>` produced from the C callback buffer.
7
doc/docs/api-reference/cpp/delegates-and-events/sessionterminationhandler.md
+1
@@ -1,6 +1,7 @@
1 # SessionTerminationHandler
2
3 Observed use:
4 +
5 - `Session::Terminated` raises one argument: `SessionTerminationReason reason`.
6
7 ```cpp
doc/docs/api-reference/cpp/enumerations/component.md
+1
@@ -3,6 +3,7 @@
3 `WslcService::GetMissingComponents()` returns a `Component` bitmask.
4
5 Underlying values:
6 +
7 - `VirtualMachinePlatform = 1`
8 - `WslPackage = 2`
9 - `SdkNeedsUpdate = 4`
doc/docs/api-reference/cpp/enumerations/containernetworkingmode.md
+2
@@ -1,10 +1,12 @@
1 # ContainerNetworkingMode
2
3 `winrt_ContainerSettings.cpp` explicitly validates only:
4 +
5 - `None`
6 - `Bridged`
7
8 Underlying C values:
9 +
10 - `None = 0`
11 - `Bridged = 1`
12
doc/docs/api-reference/cpp/enumerations/containerstate.md
+1
@@ -3,6 +3,7 @@
3 `Container::State()` casts directly from `WslcContainerState`.
4
5 Underlying C values:
6 +
7 - `Invalid = 0`
8 - `Created = 1`
9 - `Running = 2`
doc/docs/api-reference/cpp/enumerations/deletecontaineroption.md
+1
@@ -3,6 +3,7 @@
3 `Container::Delete()` takes `DeleteContainerOption`.
4
5 Underlying values:
6 +
7 - `None = 0`
8 - `Force = 1`
9
doc/docs/api-reference/cpp/enumerations/error.md
+1
@@ -1,6 +1,7 @@
1 # Error
2
3 Underlying HRESULT values:
4 +
5 - `ImageNotFound = -2147219967`
6 - `ContainerPrefixAmbiguous = -2147219966`
7 - `ContainerNotFound = -2147219965`
doc/docs/api-reference/cpp/enumerations/imageprogressstatus.md
+1
@@ -3,6 +3,7 @@
3 `ImageProgress` casts directly from `WslcImageProgressStatus`.
4
5 Underlying C values:
6 +
7 - `Unknown = 0`
8 - `Pulling = 1`
9 - `Waiting = 2`
doc/docs/api-reference/cpp/enumerations/portprotocol.md
+1
@@ -4,6 +4,7 @@
4 - The value is passed directly to `WslcContainerPortMapping::protocol`.
5
6 Underlying C values:
7 +
8 - `TCP = 0`
9 - `UDP = 1`
10
doc/docs/api-reference/cpp/enumerations/processoutputhandle.md
+1
@@ -1,6 +1,7 @@
1 # ProcessOutputHandle
2
3 `Process::GetOutputStream(ProcessOutputHandle)` accepts these values:
4 +
5 - `StandardOutput = 1`
6 - `StandardError = 2`
7
doc/docs/api-reference/cpp/enumerations/processoutputmode.md
+2
@@ -1,11 +1,13 @@
1 # ProcessOutputMode
2
3 Underlying values:
4 +
5 - `Discard = 0`
6 - `Stream = 1`
7 - `Event = 2`
8
9 Behavior:
10 +
11 - `Discard`: no stdout/stderr events or output streams.
12 - `Stream`: `GetOutputStream(...)` can be used.
13 - `Event`: stdout/stderr are delivered by callbacks and `OutputReceived` / `ErrorReceived`.
doc/docs/api-reference/cpp/enumerations/processstate.md
+1
@@ -3,6 +3,7 @@
3 `Process::State()` casts directly from `WslcProcessState`.
4
5 Underlying C values:
6 +
7 - `Unknown = 0`
8 - `Running = 1`
9 - `Exited = 2`
doc/docs/api-reference/cpp/enumerations/sessionterminationreason.md
+1
@@ -3,6 +3,7 @@
3 `Session::OnTerminated` converts `WslcSessionTerminationReason` directly to the WinRT enum.
4
5 Underlying C values:
6 +
7 - `Unknown = 0`
8 - `Shutdown = 1`
9 - `Crashed = 2`
doc/docs/api-reference/cpp/enumerations/signal.md
+1
@@ -3,6 +3,7 @@
3 `Container::Stop()` and `Process::Signal()` cast directly to `WslcSignal`.
4
5 Underlying values:
6 +
7 - `None = 0`
8 - `SIGHUP = 1`
9 - `SIGINT = 2`
doc/docs/api-reference/cpp/enumerations/vhdtype.md
+1
@@ -1,6 +1,7 @@
1 # VhdType
2
3 Underlying values:
4 +
5 - `Dynamic = 0`
6 - `Fixed = 1`
7
doc/docs/api-reference/cpp/service-class/wslcservice.md
+2
@@ -3,12 +3,14 @@
3 Static entry points over the service-level C API.
4
5 **Methods**
6 +
7 - `GetMissingComponents()`
8 - `GetVersion()`
9 - `InstallWithDependencies()`
10 - `InstallWithDependenciesAsync()`
11
12 **Behavior notes**
13 +
14 - `GetMissingComponents()` returns a `Component` bitmask.
15 - `GetVersion()` returns a `ServiceVersion` constructed from `major`, `minor`, and `revision`.
16 - `InstallWithDependencies()` installs dependencies synchronously.
doc/docs/api-reference/cpp/settings-classes/containersettings.md
+3
@@ -1,10 +1,12 @@
1 # ContainerSettings
2
3 **Constructor**
4 +
5 - `ContainerSettings(hstring imageName)`
6 - `imageName` must be non-empty.
7
8 **Properties**
9 +
10 - `ImageName()` / setter
11 - `Name()` / setter
12 - `InitProcess()` / setter
@@ -19,6 +21,7 @@
21 - `NamedVolumes()` / setter
22
23 **Important notes**
24 +
25 - Collection setters reject `nullptr`.
26 - When converting to the C struct, null elements inside the collections are rejected.
27
doc/docs/api-reference/cpp/settings-classes/processsettings.md
+2
@@ -1,12 +1,14 @@
1 # ProcessSettings
2
3 **Properties**
4 +
5 - `WorkingDirectory()` / setter
6 - `CommandLine()` / setter
7 - `EnvironmentVariables()` / setter
8 - `OutputMode()` / setter
9
10 **Important notes**
11 +
12 - `CommandLine(nullptr)` and `EnvironmentVariables(nullptr)` are rejected.
13 - `Process::Start()` later requires a **non-empty** `CommandLine()`.
14 - `ProcessOutputMode::Event` installs C callbacks; `ProcessOutputMode::Stream` expects stream access; `Discard` is the default.
doc/docs/api-reference/cpp/settings-classes/sessionsettings.md
+2
@@ -1,11 +1,13 @@
1 # SessionSettings
2
3 **Constructor**
4 +
5 - `SessionSettings(hstring name, hstring storagePath)`
6 - `name` must be non-empty.
7 - `storagePath` must be non-empty.
8
9 **Properties**
10 +
11 - `Name()` / setter
12 - `StoragePath()` / setter
13 - `CpuCount()` / setter (`0` rejected)
doc/docs/api-reference/cpp/settings-classes/vhdoptions.md
+1
@@ -1,6 +1,7 @@
1 # VhdOptions
2
3 **Properties**
4 +
5 - `Name()` / setter
6 - `Size()` / setter
7 - `Type()` / setter
doc/docs/api-reference/csharp/core-classes/container.md
+1
@@ -19,6 +19,7 @@ public sealed class Container : IDisposable
19 ```
20
21 Notes:
22 +
23 - `Start()` has **no flags parameter**.
24 - If `InitProcess.OutputMode` is `Event` or `Stream`, `Start()` automatically requests native attach.
25 - `InitProcess` is only available when `ContainerSettings.InitProcess` was configured.
doc/docs/api-reference/csharp/core-classes/process.md
+1
@@ -23,6 +23,7 @@ public sealed class Process
23 ```
24
25 Notes:
26 +
27 - Call `Start()` only for **secondary processes** created by `Container.CreateProcess(...)`.
28 - The init process is started by `Container.Start()`.
29 - `OutputReceived` and `ErrorReceived` require `OutputMode.Event`.
doc/docs/api-reference/csharp/data-classes/containerportmapping.md
+1
@@ -17,6 +17,7 @@ public sealed class ContainerPortMapping
17 ```
18
19 Notes:
20 +
21 - `WindowsAddress` **is implemented**.
22 - It accepts only `HostNameType.Ipv4` and `HostNameType.Ipv6` values.
23 - DNS names are rejected.
doc/docs/api-reference/csharp/settings-classes/containersettings.md
+1
@@ -23,6 +23,7 @@ public sealed class ContainerSettings
23 ```
24
25 Notes:
26 +
27 - `PortMappings`, `Volumes`, and `NamedVolumes` are mutable collections.
28 - `InitProcess` is optional.
29 - `NetworkingMode` is nullable; `null` means “leave default behavior”.
doc/docs/api-reference/csharp/settings-classes/processsettings.md
+1
@@ -13,6 +13,7 @@ public sealed class ProcessSettings
13 ```
14
15 Notes:
16 +
17 - `CommandLine` must be non-empty before calling `Process.Start()`.
18 - The init process is started by `Container.Start()`, not by `Process.Start()`.
19 - `OutputMode.Event` enables `OutputReceived` / `ErrorReceived`.
doc/docs/api-reference/csharp/settings-classes/sessionsettings.md
+1
@@ -18,6 +18,7 @@ public sealed class SessionSettings
18 ```
19
20 Notes:
21 +
22 - `CpuCount`, `MemorySizeInMB`, and `Timeout` are optional nullable values.
23 - `Timeout` must be positive and must fit in a `uint32` millisecond count.
24 - `VhdRequirements` is optional.
doc/docs/api-reference/csharp/settings-classes/vhdoptions.md
+1
@@ -15,6 +15,7 @@ public sealed class VhdOptions
15 ```
16
17 Notes:
18 +
19 - Use `SessionSettings.VhdRequirements` for session-level storage requirements.
20 - Use `Session.CreateVhdVolume(...)` for named session volumes.
21 - `Owner` is intended for named-volume creation and is rejected on `SessionSettings.VhdRequirements`.
doc/docs/debugging.md
+1
@@ -15,6 +15,7 @@ wpr -stop logs.ETL
15 ```
16
17 The consolidated `wsl.wprp` file includes multiple profiles for different scenarios:
18 +
19 - `WSL` - General WSL tracing (default)
20 - `WSL-Storage` - Enhanced storage tracing
21 - `WSL-Networking` - Comprehensive networking tracing