API reference docs via docfx

.github/workflows/build-docs.yml

@@ -0,0 +1,37 @@
+name: Build Docs
+
+on: push
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build Docs
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v6
+
+      - name: Setup .NET SDK
+        uses: actions/setup-dotnet@v5
+        with:
+          global-json-file: global.json
+
+      - name: Restore docfx
+        working-directory: docs
+        run: dotnet tool restore
+
+      - name: Restore Projects
+        run: |
+          dotnet restore PowerSync/PowerSync.Common/PowerSync.Common.csproj -p:TargetFrameworks=net8.0
+          dotnet restore PowerSync/PowerSync.Maui/PowerSync.Maui.csproj -p:TargetFrameworks=net8.0
+
+      - name: Generate API Metadata
+        working-directory: docs
+        run: dotnet docfx metadata docfx.json --warningsAsErrors --noRestore
+
+      - name: Build Docs
+        working-directory: docs
+        run: dotnet docfx build docfx.json --warningsAsErrors

.github/workflows/deploy-docs.yml

@@ -0,0 +1,61 @@
+name: Deploy Docs to GitHub Pages
+
+on: workflow_dispatch
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Build Docs
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v6
+
+      - name: Setup .NET SDK
+        uses: actions/setup-dotnet@v5
+        with:
+          global-json-file: global.json
+
+      - name: Restore docfx
+        working-directory: docs
+        run: dotnet tool restore
+
+      - name: Restore Projects
+        run: |
+          dotnet restore PowerSync/PowerSync.Common/PowerSync.Common.csproj -p:TargetFrameworks=net8.0
+          dotnet restore PowerSync/PowerSync.Maui/PowerSync.Maui.csproj -p:TargetFrameworks=net8.0
+
+      - name: Generate API Metadata
+        working-directory: docs
+        run: dotnet docfx metadata docfx.json --warningsAsErrors --noRestore
+
+      - name: Build Docs
+        working-directory: docs
+        run: dotnet docfx build docfx.json --warningsAsErrors
+
+      - name: Upload Pages Artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./docs/_site
+
+  deploy:
+    name: Deploy to GitHub Pages
+    runs-on: ubuntu-latest
+    needs: build
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

Directory.build.props

@@ -2,8 +2,9 @@
 <Project>
     <PropertyGroup>
         <MSBuildWarningsAsMessages>$(MSBuildWarningsAsMessages);NETSDK1202</MSBuildWarningsAsMessages>
+        <GenerateDocumentationFile>true</GenerateDocumentationFile>
     </PropertyGroup>
     <ItemGroup>
         <Compile Include="$(MSBuildThisFileDirectory)IsExternalInit.cs" Visible="false" />
     </ItemGroup>
-</Project>
+</Project>

docs/.config/dotnet-tools.json

@@ -0,0 +1,13 @@
+{
+  "version": 1,
+  "isRoot": true,
+  "tools": {
+    "docfx": {
+      "version": "2.78.5",
+      "commands": [
+        "docfx"
+      ],
+      "rollForward": false
+    }
+  }
+}

docs/.gitignore

@@ -0,0 +1,3 @@
+api/
+_site/
+obj/

docs/README.md

@@ -0,0 +1,30 @@
+# API Reference Docs
+
+API documentation website for the PowerSync .NET SDK, generated via `docfx`.
+
+## Building locally
+
+1. Install `docfx`:
+
+`docfx` is installed as a local .NET tool.
+
+```bash
+cd docs
+dotnet tool restore
+```
+
+2. Build and serve on `http://localhost:8080`:
+
+```bash
+dotnet tool restore
+dotnet docfx docfx.json --serve
+```
+
+## Publishing
+
+- `.github/workflows/build-docs.yml`: Builds the site on every push.
+- `.github/workflows/deploy-docs.yml`: Builds and publishes the site on push to `main`.
+
+## Notes
+
+Projects are built with only the `net8.0` target present (see the `properties` field in `docfx.json`) so that the MAUI workloads and the native `powersync-sqlite-core` binaries are not required to build the docs.

docs/docfx.json

@@ -0,0 +1,63 @@
+{
+  "$schema": "https://raw.githubusercontent.com/dotnet/docfx/main/schemas/docfx.schema.json",
+  "metadata": [
+    {
+      "src": [
+        {
+          "src": "../PowerSync",
+          "files": [
+            "PowerSync.Common/PowerSync.Common.csproj",
+            "PowerSync.Maui/PowerSync.Maui.csproj"
+          ]
+        }
+      ],
+      "dest": "api",
+      "filter": "filter.yml",
+      "properties": {
+        "TargetFramework": "net8.0",
+        "TargetFrameworks": "net8.0"
+      },
+      "namespaceLayout": "nested",
+      "memberLayout": "separatePages",
+      "enumSortOrder": "declaringOrder",
+      "outputFormat": "mref"
+    }
+  ],
+  "build": {
+    "content": [
+      {
+        "files": ["**/*.{md,yml}"],
+        "exclude": [
+          "_site/**",
+          "obj/**",
+          "template/**",
+          "README.md",
+          "filter.yml"
+        ]
+      }
+    ],
+    "resource": [
+      {
+        "files": ["index.html", "images/**"]
+      }
+    ],
+    "output": "_site",
+    "template": ["default", "modern", "template"],
+    "globalMetadata": {
+      "_appName": "PowerSync .NET",
+      "_appTitle": "PowerSync .NET SDK",
+      "_appFaviconPath": "images/powersync.png",
+      "_appLogoPath": "images/powersync.png",
+      "_appFooter": "PowerSync .NET SDK &middot; <a href=\"https://docs.powersync.com\">PowerSync Docs</a>",
+      "_enableSearch": true,
+      "_disableContribution": false,
+      "_gitContribute": {
+        "repo": "https://github.com/powersync-ja/powersync-dotnet",
+        "branch": "main",
+        "apiSpecFolder": "docs"
+      },
+      "pdf": false
+    },
+    "postProcessors": ["ExtractSearchIndex"]
+  }
+}

docs/filter.yml

@@ -0,0 +1,5 @@
+apiRules:
+  # Ignore the `build/ApiDefinition.cs` file in PowerSync.Maui (required to build for Apple targets)
+  - exclude:
+      uidRegex: ^PowerSync\.Maui\.build$
+      type: Namespace

docs/index.html

@@ -0,0 +1,15 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>PowerSync .NET API Reference</title>
+    <link rel="canonical" href="api/PowerSync.html" />
+    <meta http-equiv="refresh" content="0; url=api/PowerSync.html" />
+    <script>
+      location.replace("api/PowerSync.html");
+    </script>
+  </head>
+  <body>
+    <p>Redirecting to the <a href="api/PowerSync.html">PowerSync .NET API reference</a>.</p>
+  </body>
+</html>

docs/template/public/main.css

@@ -0,0 +1,5 @@
+img#logo {
+  height: 28px;
+  width: auto;
+  margin-right: 0.5rem;
+}

docs/toc.yml

@@ -0,0 +1,2 @@
+- name: API Reference
+  uid: PowerSync