docs: add runnable documentation examples for the public API (#4503)

## Summary

**Runnable documentation examples now cover the public API of every lean
ReactiveUI package, one page project per handbook page.**

- **New page projects under `src/examples/Documentation/Pages`.** Each
project matches one page of the handbook on reactiveui.net (view models,
commands, bindings, activation, interactions, view location, routing,
collections, message bus, scheduling, persistence, testing, the app
builder, registration, reflection) and runs as a console app that prints
what each example does.
- **Platform page projects for WPF, WinForms, WinUI, Blend and Drawing,
MAUI, Blazor and Android.** Each is a small realistic app (a school
timetable, a weather station dashboard, a course list) that runs its
scenario end to end and prints the result; the Windows apps expose
`--smoke`.
- **Every example states its output.** Each example method ends in an
`// Output:` block, and the website quotes the examples verbatim.
- **Examples follow the merged fixes.** Routing uses the #4497
navigation streams, WinUI shows the #4496 AOT-safe hosts with their
`*Unsafe` twins as the explicit opt-in, and the builder, MAUI host,
ReactiveRecord, suspension and Android orientation examples show the
fixed behaviour.
- **CI tests only the projects under `tests/`.** The solution now builds
the example apps, and `dotnet test` over the whole solution tried to run
them, including the Android and MAUI apps, which need a device.
- **The examples build with the same rules as Refit's.**
`src/examples/Documentation` carries Refit's `.editorconfig` (explicit
types instead of `var`), and `src/examples/Directory.Build.props` marks
the examples as not packable.

## Why

**The handbook needs an example for every public member, and each
example has to compile and run against the current code.**

- The pages on reactiveui.net quote these projects, so a page cannot
drift from the API without a build or output check failing.
- Members that no example calls are reviewed one by one: the platform or
the framework calls them, another ReactiveUI package uses them, or they
need hardware the examples cannot run on.

## Breaking changes

**None.** The examples are not packaged.

## How this was verified

**Every page project builds with no warnings, and each project's printed
output matches its `// Output:` blocks.** The Windows apps ran their
`--smoke` scenario on Windows, and the Android app ran its full scenario
on an emulator. iOS and Mac Catalyst were not run.

## Notes for the reviewer

**The code is sample code, so review it for readability and realism, not
for architecture.**

- Start with any one page project's `Program.cs`, which lists that
page's examples in reading order.
- `src/examples/Documentation/Directory.Build.props`,
`src/examples/Directory.Build.props`, `.editorconfig` and the
`reactiveui.slnx` entries are the only build changes.
- Overload families such as `WithInstance` are shown at one and
two arguments only; the pages state how many the family supports.
- The WinUI maintenance panel uses `RoutedViewHostUnsafe` and
`ViewModelViewHostUnsafe` for a view added with `Map`, because the
default hosts cannot find a mapped view until #4502 is fixed.

## Checklist
- [x] I have read the [Contribute
guide](https://www.reactiveui.net/contribute/index.html)
- [x] The PR title follows [Conventional
Commits](https://www.conventionalcommits.org/)
- [x] Tests cover this change, or the summary says why they do not
- [ ] New or changed public API has XML documentation

Author: glennawatson

.github/workflows/ci-build.yml

@@ -22,5 +22,7 @@ jobs:
       productNamespacePrefix: "ReactiveUI"
       installWorkloads: true
       installWindowsAppRuntime: true
+      # Test only the test projects: the solution also builds the documentation example apps, which are not tests.
+      testProjects: tests/**/*.csproj
     secrets:
       CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}

.github/workflows/sonarcloud.yml

@@ -16,6 +16,8 @@ jobs:
             productNamespacePrefix: ReactiveUI
             installWorkloads: true
             installWindowsAppRuntime: true
+            # Test only the test projects: the solution also builds the documentation example apps, which are not tests.
+            testProjects: tests/**/*.csproj
             sonarProjectKey: reactiveui_ReactiveUI
             sonarOrganization: reactiveui
             sonarExclusions: '**/tests/**,**/integrationtests/**,**/benchmarks/**,**/examples/**,**/TestResults/**'

src/examples/Directory.Build.props

@@ -10,4 +10,9 @@
 
   
   <Import Project="$([MSBuild]::GetPathOfFileAbove('Directory.Build.props', '$(MSBuildThisFileDirectory)../'))" />
+
+  <PropertyGroup>
+    <IsPackable>falseIsPackable>
+    <LangVersion>14.0LangVersion>
+  PropertyGroup>
 Project>

src/examples/Documentation/.editorconfig

@@ -0,0 +1,55 @@
+# This policy applies to the complete runnable documentation examples.
+# All compiler, correctness, security, performance and remaining style rules are inherited.
+
+[*.cs]
+# Explicit local types let readers understand a website block without following another method.
+# Keep the style analyzer enabled and configure it to enforce explicit types in these samples only.
+stylesharp.use_var = never
+stylesharp.SST2271.use_var = never
+csharp_style_var_for_built_in_types = false:suggestion
+csharp_style_var_when_type_is_apparent = false:suggestion
+csharp_style_var_elsewhere = false:suggestion
+
+# Documentation-specific exemptions belong only in the website documentation folder.
+# Complete source examples keep the inherited XML documentation diagnostics enabled.
+
+# Readers learn from concrete values ("Ada", "/imports/records", 10). Naming every literal as a constant only for
+# the analyzer sends them scrolling away from the line they are reading.
+dotnet_diagnostic.SST1486.severity = none
+dotnet_diagnostic.SST1471.severity = none
+# Samples show results as comments beside the line that produces them, which can look like commented-out code.
+dotnet_diagnostic.SST1148.severity = none
+# A sample's own "throw if the result is wrong" check is not part of an API contract that needs  docs.
+dotnet_diagnostic.SST1662.severity = none
+# Samples build a client inline so the reader sees where it comes from; IHttpClientFactory is covered separately.
+dotnet_diagnostic.PSH1418.severity = none
+
+# Samples name the type they create ("new Person(1, \"Ada\")") so a reader never has to work out what "new(...)" builds.
+dotnet_diagnostic.SST2202.severity = none
+dotnet_diagnostic.IDE0090.severity = none
+# One initializer entry per line, with braces on their own lines, reads better in samples than one long line.
+dotnet_diagnostic.SST1531.severity = none
+# Samples call methods for their effect and ignore the value, as readers do; "_ =" discards only add noise here.
+dotnet_diagnostic.SST2221.severity = none
+dotnet_diagnostic.IDE0058.severity = none
+dotnet_diagnostic.CA1806.severity = none
+# [MethodImpl(AggressiveInlining)] on small sample helpers is performance tuning that distracts from what they show.
+dotnet_diagnostic.PSH1410.severity = none
+# A view starts its WhenActivated block in its constructor, which hands 'this' to ReactiveUI. That is the pattern
+# ReactiveUI documents for every view, so samples show it without a suppression attribute on each constructor.
+dotnet_diagnostic.SST2403.severity = none
+
+[TestingFrameworks/**/*.cs]
+# These tests are written for a beginner reading real test-framework code, not for API consumers browsing
+# IntelliSense: a plain "// Problem: ..." comment naming what the test is for reads better here than a
+# required /// doc comment on every [Fact]/[Test]/[TestMethod], and public test classes/methods do not need
+# XML docs (GenerateDocumentationFile is also off for these projects; see their .csproj).
+dotnet_diagnostic.SST1600.severity = none
+dotnet_diagnostic.SST1601.severity = none
+dotnet_diagnostic.SST1663.severity = none
+# A tiny record and JSON context used only by these tests do not need a [DebuggerDisplay]; that is
+# production-strictness these samples do not need.
+dotnet_diagnostic.SST2334.severity = none
+# xUnit's "pass TestContext.Current.CancellationToken" suggestion would make the xUnit project's tests differ
+# from the otherwise-identical NUnit/MSTest/TUnit versions just to satisfy one framework's analyzer.
+dotnet_diagnostic.xUnit1051.severity = none

src/examples/Documentation/Common/ExampleApp.cs

@@ -23,7 +23,7 @@ public static class ExampleApp
     /// Adds the example's own registrations, such as its views.
     public static void Start(Action<IReactiveUIBuilder> configure)
     {
-        var builder = RxAppBuilder.CreateReactiveUIBuilder().WithMainThreadScheduler(Sequencer.Immediate);
+        IReactiveUIBuilder builder = RxAppBuilder.CreateReactiveUIBuilder().WithMainThreadScheduler(Sequencer.Immediate);
         _ = builder.WithCoreServices().BuildApp();
         configure(builder);
     }

src/examples/Documentation/Common/Todo/InMemoryTodoStore.cs

@@ -53,7 +53,7 @@ public async Task AddAsync(string title, CancellationToken cancellatio
     public async Task<TodoItem> CompleteAsync(int id, CancellationToken cancellationToken)
     {
         await Task.Delay(Latency, cancellationToken).ConfigureAwait(false);
-        var row = _rows.Find(row => row.Id == id) ?? throw new TodoStoreException($"Item {id} does not exist.");
+        TodoItem row = _rows.Find(row => row.Id == id) ?? throw new TodoStoreException($"Item {id} does not exist.");
         row.IsDone = true;
         return row.Clone();
     }

src/examples/Documentation/Common/Todo/TodoListViewModel.cs

@@ -36,7 +36,7 @@ public TodoListViewModel(ITodoStore store)
         Load = ReactiveCommand.CreateFromTask(_store.QueryAsync);
         _subscriptions.Add(Load.Subscribe(rows => AllItems = rows));
 
-        var canAdd = this.WhenAnyValue(x => x.NewTitle).Select(static title => !string.IsNullOrWhiteSpace(title));
+        IObservable<bool> canAdd = this.WhenAnyValue(x => x.NewTitle).Select(static title => !string.IsNullOrWhiteSpace(title));
         Add = ReactiveCommand.CreateFromTask(cancellationToken => _store.AddAsync(NewTitle.Trim(), cancellationToken), canAdd);
         _subscriptions.Add(Add.Subscribe(added =>
         {

src/examples/Documentation/Directory.Build.props

@@ -17,6 +17,10 @@
   <ItemGroup>
     <AssemblyAttribute Include="System.Diagnostics.CodeAnalysis.ExcludeFromCodeCoverage" />
     <ProjectReference Include="$(MSBuildThisFileDirectory)../../ReactiveUI/ReactiveUI.csproj" />
+  ItemGroup>
+
+  
+  <ItemGroup>
     <Compile Include="$(MSBuildThisFileDirectory)Common/**/*.cs" Link="Common/%(RecursiveDir)%(Filename)%(Extension)" />
   ItemGroup>
 

src/examples/Documentation/Pages/collections/AutoPersistExamples.cs

@@ -0,0 +1,104 @@
+// Copyright (c) 2009-2026 .NET Foundation and Contributors. All rights reserved.
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+// See the LICENSE file in the project root for full license information.
+
+using System.Collections.ObjectModel;
+
+namespace ReactiveUI.Documentation.Collections;
+
+/// Shows ActOnEveryObject, which calls a method for every object already in a collection and for every
+/// one added or removed afterwards.
+public static class AutoPersistExamples
+{
+    /// ActOnEveryObject reports the items already in the collection first, then every later add and remove.
+    public static void TrackAddsAndRemovesOnAnObservableCollection()
+    {
+        ObservableCollection<Product> inventory = [new Product("Kettle", 4)];
+        List<string> log = [];
+        using IDisposable subscription = inventory.ActOnEveryObject(
+            product => log.Add($"add {product.Name}"),
+            product => log.Add($"remove {product.Name}"));
+
+        inventory.Add(new Product("Toaster", 2));
+        inventory.RemoveAt(0);
+
+        foreach (string entry in log)
+        {
+            Console.WriteLine(entry);
+        }
+
+        // Output:
+        // add Kettle
+        // add Toaster
+        // remove Kettle
+    }
+
+    /// ActOnEveryObject also works on the  a view model exposes to a view.
+    public static void TrackAddsAndRemovesOnAReadOnlyView()
+    {
+        ObservableCollection<Product> inventory = [new Product("Kettle", 4)];
+        ReadOnlyObservableCollection<Product> readOnlyInventory = new(inventory);
+        List<string> log = [];
+        using IDisposable subscription = readOnlyInventory.ActOnEveryObject(
+            product => log.Add($"add {product.Name}"),
+            product => log.Add($"remove {product.Name}"));
+
+        inventory.Add(new Product("Toaster", 2));
+
+        foreach (string entry in log)
+        {
+            Console.WriteLine(entry);
+        }
+
+        // Output:
+        // add Kettle
+        // add Toaster
+    }
+
+    /// ActOnEveryObject also subscribes directly to a change-set stream produced by ToReactiveChangeSet.
+    public static void TrackAddsAndRemovesFromAChangeSetStream()
+    {
+        ObservableCollection<Product> inventory = [new Product("Kettle", 4)];
+        List<string> log = [];
+        using IDisposable subscription = inventory.ToReactiveChangeSet().ActOnEveryObject(
+            product => log.Add($"add {product.Name}"),
+            product => log.Add($"remove {product.Name}"));
+
+        inventory.Add(new Product("Toaster", 2));
+
+        foreach (string entry in log)
+        {
+            Console.WriteLine(entry);
+        }
+
+        // Output:
+        // add Kettle
+        // add Toaster
+    }
+
+    /// A collection that only raises CollectionChanged itself also works with ActOnEveryObject.
+    public static void TrackAddsAndRemovesOnACustomCatalog()
+    {
+        ShopCatalog catalog = new();
+        catalog.Stock(new Product("Kettle", 4));
+
+        List<string> log = [];
+        using IDisposable subscription = catalog.ActOnEveryObject<Product, ShopCatalog>(
+            product => log.Add($"add {product.Name}"),
+            product => log.Add($"remove {product.Name}"));
+
+        catalog.Stock(new Product("Toaster", 2));
+        catalog.SellOut(catalog.First(static product => product.Name == "Kettle"));
+
+        foreach (string entry in log)
+        {
+            Console.WriteLine(entry);
+        }
+
+        // Output:
+        // add Kettle
+        // add Toaster
+        // remove Kettle
+    }
+}