diff --git a/.github/workflows/build-docs.yml b/.github/workflows/build-docs.yml new file mode 100644 index 00000000..2e801bda --- /dev/null +++ b/.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 diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml new file mode 100644 index 00000000..2a4db78b --- /dev/null +++ b/.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 diff --git a/Directory.build.props b/Directory.build.props index bcdc24ac..fe14bb0e 100644 --- a/Directory.build.props +++ b/Directory.build.props @@ -2,8 +2,9 @@ $(MSBuildWarningsAsMessages);NETSDK1202 + true - \ No newline at end of file + diff --git a/docs/.config/dotnet-tools.json b/docs/.config/dotnet-tools.json new file mode 100644 index 00000000..12ab7ac1 --- /dev/null +++ b/docs/.config/dotnet-tools.json @@ -0,0 +1,13 @@ +{ + "version": 1, + "isRoot": true, + "tools": { + "docfx": { + "version": "2.78.5", + "commands": [ + "docfx" + ], + "rollForward": false + } + } +} \ No newline at end of file diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 00000000..d568c5c2 --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1,3 @@ +api/ +_site/ +obj/ diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000..74e25b9b --- /dev/null +++ b/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. diff --git a/docs/docfx.json b/docs/docfx.json new file mode 100644 index 00000000..4c7aee77 --- /dev/null +++ b/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 · PowerSync Docs", + "_enableSearch": true, + "_disableContribution": false, + "_gitContribute": { + "repo": "https://github.com/powersync-ja/powersync-dotnet", + "branch": "main", + "apiSpecFolder": "docs" + }, + "pdf": false + }, + "postProcessors": ["ExtractSearchIndex"] + } +} diff --git a/docs/filter.yml b/docs/filter.yml new file mode 100644 index 00000000..257f884c --- /dev/null +++ b/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 diff --git a/docs/images/powersync.png b/docs/images/powersync.png new file mode 100644 index 00000000..8d7111c8 Binary files /dev/null and b/docs/images/powersync.png differ diff --git a/docs/index.html b/docs/index.html new file mode 100644 index 00000000..9d17be8c --- /dev/null +++ b/docs/index.html @@ -0,0 +1,15 @@ + + + + + PowerSync .NET API Reference + + + + + +

Redirecting to the PowerSync .NET API reference.

+ + diff --git a/docs/template/public/main.css b/docs/template/public/main.css new file mode 100644 index 00000000..316cb046 --- /dev/null +++ b/docs/template/public/main.css @@ -0,0 +1,5 @@ +img#logo { + height: 28px; + width: auto; + margin-right: 0.5rem; +} diff --git a/docs/toc.yml b/docs/toc.yml new file mode 100644 index 00000000..8c52d26d --- /dev/null +++ b/docs/toc.yml @@ -0,0 +1,2 @@ +- name: API Reference + uid: PowerSync