Build the initial documentation site (#2088)

* Build initial documentation site

* Address documentation review feedback

* Clarify WebAssembly and native loading guidance

Author: shimat

.github/workflows/docfx.yml

@@ -1,13 +1,18 @@
 name: DocFX
 
 on:
+  pull_request:
+    paths:
+      - "docs/**"
+      - "src/OpenCvSharp/**"
+      - ".github/workflows/docfx.yml"
   push:
     branches:
       - main
   workflow_dispatch:
 
 concurrency:
-  group: "pages"
+  group: "docfx-${{ github.ref }}"
   cancel-in-progress: false
 
 jobs:
@@ -45,15 +50,16 @@ jobs:
           path: docs/docfx/_site
 
   deploy:
-   needs: build
-   permissions:
-     pages: write
-     id-token: write
-   environment:
-     name: github-pages
-     url: ${{ steps.deployment.outputs.page_url }}
-   runs-on: ubuntu-latest
-   steps:
-     - name: Deploy to GitHub Pages
-       id: deployment
-       uses: actions/deploy-pages@v5
+    if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main'
+    needs: build
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v5

README.md

@@ -146,7 +146,7 @@ This profile is used by:
 - `OpenCvSharp5.official.runtime.linux-x64.slim`
 
 ## Usage
-For more details, refer to the **[samples](https://github.com/shimat/opencvsharp_samples/)** and **[Wiki](https://github.com/shimat/opencvsharp/wiki)** pages.
+For step-by-step guides, package selection, and troubleshooting, see the **[OpenCvSharp documentation](https://shimat.github.io/opencvsharp/)**. More complete programs are available in the **[samples repository](https://github.com/shimat/opencvsharp_samples/)**.
 
 **Always remember to release Mat and other IDisposable resources using the `using` syntax:**
 ```C#
@@ -193,8 +193,8 @@ https://github.com/shimat/opencvsharp_samples/
 
 Interactive browser-based samples (Blazor WebAssembly) are maintained separately at https://github.com/shimat/opencvsharp_blazor_sample/, with a [live demo](https://shimat.github.io/opencvsharp_blazor_sample/).
 
-## API Documents
-http://shimat.github.io/opencvsharp/api/OpenCvSharp.html
+## Documentation
+https://shimat.github.io/opencvsharp/
 
 ## NuGet
 

docs/docfx/api/index.md

@@ -21,4 +21,4 @@ The API is organized into the following namespaces:
 
 ## Getting Started
 
-See the [Introduction](../articles/intro.md) for getting started with OpenCvSharp.
+See the [guides overview](../articles/index.md) for getting started with OpenCvSharp.

docs/docfx/articles/getting-started/first-application.md

@@ -0,0 +1,61 @@
+# Your First Application
+
+This example reads an image, converts it to grayscale, and saves the result. It does not open a native window, so it also works with the Linux headless runtime package.
+
+## Prepare an input image
+
+Place a JPEG or PNG image named `input.jpg` in the project directory. Configure it to be copied to the output directory by adding the following item to the project file:
+
+```xml
+<ItemGroup>
+  <None Update="input.jpg" CopyToOutputDirectory="PreserveNewest" />
+</ItemGroup>
+```
+
+## Add the code
+
+Replace `Program.cs` with:
+
+```csharp
+using OpenCvSharp;
+
+using var source = Cv2.ImRead("input.jpg", ImreadModes.Color);
+if (source.Empty())
+{
+    throw new InvalidOperationException("Could not read input.jpg.");
+}
+
+using var grayscale = new Mat();
+Cv2.CvtColor(source, grayscale, ColorConversionCodes.BGR2GRAY);
+
+if (!Cv2.ImWrite("output.png", grayscale))
+{
+    throw new InvalidOperationException("Could not write output.png.");
+}
+
+Console.WriteLine($"Created output.png ({grayscale.Width} x {grayscale.Height}).");
+```
+
+## Run the application
+
+```bash
+dotnet run
+```
+
+The application creates `output.png` in its working directory.
+
+## What the code does
+
+- `Cv2.ImRead` decodes the input file into a `Mat`.
+- `source.Empty()` detects a missing or unsupported input image.
+- `Cv2.CvtColor` converts the image from OpenCV's default BGR channel order to grayscale.
+- `Cv2.ImWrite` selects an encoder from the output file extension and writes the image.
+- The `using` declarations release the native memory owned by both `Mat` instances.
+
+OpenCvSharp objects that own native resources must be disposed. Read [Resource Management](../guides/resource-management.md) before building a long-running application.
+
+## Next steps
+
+- Browse the [OpenCvSharp API reference](xref:OpenCvSharp).
+- Explore the [OpenCvSharp sample projects](https://github.com/shimat/opencvsharp_samples).
+- Check [Native Library Loading](../troubleshooting/native-library-loading.md) if the application builds but fails at run time.

docs/docfx/articles/getting-started/installation.md

@@ -0,0 +1,116 @@
+# Installation
+
+This page creates a .NET console application and installs the packages selected in [Choose a Version and Package](package-selection.md). The commands require the [.NET 8 SDK or later](https://dotnet.microsoft.com/download).
+
+## Create a project
+
+```bash
+dotnet new console -n OpenCvSharpExample
+cd OpenCvSharpExample
+```
+
+## Windows x64
+
+The all-in-one package is the simplest option for Windows x64:
+
+```bash
+dotnet add package OpenCvSharp5.Windows
+```
+
+For the reduced module set, use `OpenCvSharp5.Windows.Slim` instead.
+
+## Windows ARM64
+
+```bash
+dotnet add package OpenCvSharp5
+dotnet add package OpenCvSharp5.runtime.win-arm64
+```
+
+Use `OpenCvSharp5.runtime.win-arm64.slim` instead of the full runtime when the reduced module set is sufficient.
+
+## Linux x64
+
+For a desktop application that uses native OpenCV windows:
+
+```bash
+dotnet add package OpenCvSharp5
+dotnet add package OpenCvSharp5.official.runtime.linux-x64
+```
+
+For a service or container that does not use `Cv2.ImShow`, `Cv2.WaitKey`, or other `highgui` APIs:
+
+```bash
+dotnet add package OpenCvSharp5
+dotnet add package OpenCvSharp5.official.runtime.linux-x64.headless
+```
+
+The full runtime requires GTK3. On a minimal Ubuntu or Debian installation, install it with:
+
+```bash
+sudo apt-get update
+sudo apt-get install libgtk-3-0
+```
+
+The official Linux x64 packages require glibc 2.28 or later.
+
+## Linux ARM64
+
+```bash
+dotnet add package OpenCvSharp5
+dotnet add package OpenCvSharp5.runtime.linux-arm64
+```
+
+## macOS
+
+For Apple Silicon:
+
+```bash
+dotnet add package OpenCvSharp5
+dotnet add package OpenCvSharp5.runtime.osx.arm64
+```
+
+For an Intel Mac:
+
+```bash
+dotnet add package OpenCvSharp5
+dotnet add package OpenCvSharp5.runtime.osx.x64
+```
+
+## WebAssembly
+
+WebAssembly uses static native linking and requires a Blazor WebAssembly project rather than the console project created above. Install the WebAssembly build tools and create a standalone Blazor WebAssembly application:
+
+```bash
+dotnet workload install wasm-tools
+dotnet new blazorwasm -n OpenCvSharpWasmExample
+cd OpenCvSharpWasmExample
+dotnet add package OpenCvSharp5
+dotnet add package OpenCvSharp5.runtime.wasm
+```
+
+Add the following properties to the project file:
+
+```xml
+<PropertyGroup>
+  <WasmInitialHeapSize>268435456</WasmInitialHeapSize>
+  <WasmAllowUndefinedSymbols>true</WasmAllowUndefinedSymbols>
+</PropertyGroup>
+```
+
+The larger initial heap accommodates the statically linked OpenCV runtime. `WasmAllowUndefinedSymbols` is currently a package and toolchain-specific linker workaround: it allows the static link to complete even though the managed assembly declares APIs for OpenCV modules that are not included in the WebAssembly build. Calling one of those unavailable APIs will still fail at run time. This property does not configure exception handling; the runtime package supplies the native archive and its required `WasmEnableExceptionHandling` setting.
+
+See the [OpenCvSharp Blazor sample](https://github.com/shimat/opencvsharp_blazor_sample) for a complete browser application.
+
+## Verify the package references
+
+```bash
+dotnet list package
+dotnet restore
+dotnet build
+```
+
+The package list should contain `OpenCvSharp5` and exactly one runtime package for the deployment target, unless you selected a Windows convenience package.
+
+## Next step
+
+Continue to [Your First Application](first-application.md).

docs/docfx/articles/getting-started/package-selection.md

@@ -0,0 +1,46 @@
+# Choose a Version and Package
+
+OpenCvSharp uses separate managed and native packages. Every application needs the managed OpenCvSharp package and a native runtime package for its target operating system and architecture. The Windows convenience packages include both.
+
+## Choose OpenCvSharp5 or OpenCvSharp4
+
+| Package family | OpenCV version | .NET support | Recommended use |
+|---|---|---|---|
+| `OpenCvSharp5.*` | OpenCV 5.x | .NET 8 or later | New applications |
+| `OpenCvSharp4.*` | OpenCV 4.13 | .NET Framework 4.6.1 or later, .NET Standard 2.0/2.1, and .NET 8 or later | Existing applications and applications that require older .NET targets |
+
+The examples in this documentation use OpenCvSharp5. Replace `OpenCvSharp5` with the corresponding `OpenCvSharp4` package only when your application must use the OpenCvSharp4 family.
+
+## Choose a runtime package
+
+| Target | Packages |
+|---|---|
+| Windows x64 | `OpenCvSharp5.Windows` |
+| Windows ARM64 | `OpenCvSharp5` and `OpenCvSharp5.runtime.win-arm64` |
+| Linux x64 with GUI support | `OpenCvSharp5` and `OpenCvSharp5.official.runtime.linux-x64` |
+| Linux x64 without GUI support | `OpenCvSharp5` and `OpenCvSharp5.official.runtime.linux-x64.headless` |
+| Linux x64 with a reduced module set | `OpenCvSharp5` and `OpenCvSharp5.official.runtime.linux-x64.slim` |
+| Linux ARM64 | `OpenCvSharp5` and `OpenCvSharp5.runtime.linux-arm64` |
+| macOS Intel | `OpenCvSharp5` and `OpenCvSharp5.runtime.osx.x64` |
+| macOS Apple Silicon | `OpenCvSharp5` and `OpenCvSharp5.runtime.osx.arm64` |
+| WebAssembly | `OpenCvSharp5` and `OpenCvSharp5.runtime.wasm` |
+
+Use only one native runtime package for a given deployment target. The runtime package must match the operating system and process architecture.
+
+## Full, headless, and slim Linux packages
+
+The full Linux x64 package contains the complete module set, including `highgui`, and therefore uses GTK3 for APIs such as `Cv2.ImShow` and `Cv2.WaitKey`.
+
+The headless package contains the same module set as the full package except for `highgui`. It is the usual choice for services and containers that need features such as `videoio`, DNN, ML, or contrib modules but do not display native windows.
+
+The slim package has no GUI dependency and reduces the native module set. It omits contrib, DNN, `videoio`, and `highgui`, among other modules. Choose it only when the reduced feature set is sufficient.
+
+## Windows convenience packages
+
+`OpenCvSharp5.Windows` combines the managed library, Windows x64 native runtime, GDI+ extensions, and WPF extensions where applicable. `OpenCvSharp5.Windows.Slim` provides the corresponding reduced native module set.
+
+For Windows ARM64, reference `OpenCvSharp5` and `OpenCvSharp5.runtime.win-arm64` separately. FFmpeg-based video I/O is not included in the Windows ARM64 runtime package.
+
+## Next step
+
+Continue to [Installation](installation.md).

docs/docfx/articles/guides/resource-management.md

@@ -0,0 +1,83 @@
+# Resource Management
+
+Many OpenCvSharp types wrap native OpenCV objects. Dispose objects that implement `IDisposable` as soon as they are no longer needed so that long-running applications do not retain native memory.
+
+## Prefer using declarations
+
+Use a `using` declaration for each `Mat` that owns a result:
+
+```csharp
+using var source = Cv2.ImRead("input.jpg", ImreadModes.Color);
+using var blurred = new Mat();
+
+Cv2.GaussianBlur(source, blurred, new Size(5, 5), 0);
+Cv2.ImWrite("blurred.png", blurred);
+```
+
+The variables are disposed automatically at the end of the current scope.
+
+## Dispose temporary results in loops
+
+Objects created inside a loop should normally be disposed during each iteration:
+
+```csharp
+foreach (var fileName in fileNames)
+{
+    using var source = Cv2.ImRead(fileName);
+    using var resized = new Mat();
+
+    Cv2.Resize(source, resized, new Size(640, 480));
+    Cv2.ImWrite(Path.ChangeExtension(fileName, ".resized.jpg"), resized);
+}
+```
+
+Waiting for garbage collection is not a substitute for deterministic disposal. The garbage collector tracks managed memory and does not have an accurate view of the native memory held by a `Mat`.
+
+## Mat expressions
+
+OpenCvSharp arithmetic operators build a managed `MatExpr` expression. Intermediate expression nodes do not own native resources. Dispose the input matrices and the materialized result:
+
+```csharp
+using var source = Cv2.ImRead("input.jpg", ImreadModes.Grayscale);
+using Mat adjusted = 255 - source * 0.8;
+
+Cv2.ImWrite("adjusted.png", adjusted);
+```
+
+The intermediate `source * 0.8` expression does not need its own `using` declaration.
+
+## Returning a Mat
+
+Do not dispose a `Mat` before returning it to the caller. Transfer ownership explicitly through the method contract:
+
+```csharp
+static Mat LoadGrayscale(string fileName)
+{
+    using var source = Cv2.ImRead(fileName, ImreadModes.Color);
+    var grayscale = new Mat();
+    try
+    {
+        Cv2.CvtColor(source, grayscale, ColorConversionCodes.BGR2GRAY);
+        return grayscale;
+    }
+    catch
+    {
+        grayscale.Dispose();
+        throw;
+    }
+}
+
+using var image = LoadGrayscale("input.jpg");
+```
+
+The caller owns and disposes the returned `Mat`. The method disposes the result itself if an exception occurs before ownership can be transferred to the caller.
+
+## Windows and UI objects
+
+`Window` and other OpenCvSharp wrappers that implement `IDisposable` follow the same rule. Scope them with `using` rather than relying on finalization.
+
+## Related API
+
+- [Mat](xref:OpenCvSharp.Mat)
+- [MatExpr](xref:OpenCvSharp.MatExpr)
+- [Cv2](xref:OpenCvSharp.Cv2)