feat: Add typedoc documentation for public API and interfaces

.github/workflows/documentation.yml

@@ -0,0 +1,54 @@
+# SPDX-FileCopyrightText: Nextcloud contributors
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+name: Documentation
+
+on:
+  pull_request:
+  release:
+    types: [published]
+
+jobs:
+  build-and-deploy:
+    runs-on: ubuntu-latest
+
+    name: Build and deploy
+    steps:
+      - name: Check actor permission level
+        # Only allow admin to deploy on release
+        if: github.event.release
+        uses: skjnldsv/check-actor-permission@e591dbfe838300c007028e1219ca82cc26e8d7c5 # v2
+        with:
+          require: admin
+
+      - name: Checkout
+        uses: actions/checkout@c85c95e3d7251135ab7dc9ce3241c5835cc595a9 # v3.5.3
+
+      - name: Read package.json node and npm engines version
+        uses: skjnldsv/read-package-engines-version-actions@8205673bab74a63eb9b8093402fd9e0e018663a1 # v2.2
+        id: versions
+        with:
+          fallbackNode: '^20'
+          fallbackNpm: '^9'
+
+      - name: Set up node ${{ steps.versions.outputs.nodeVersion }}
+        uses: actions/setup-node@e33196f7422957bea03ed53f6fbb155025ffc7b8 # v3.7.0
+        with:
+          node-version: ${{ steps.versions.outputs.nodeVersion }}
+
+      - name: Set up npm ${{ steps.versions.outputs.npmVersion }}
+        run: npm i -g npm@"${{ steps.versions.outputs.npmVersion }}"
+
+      - name: Install dependencies & build
+        run: |
+          npm ci
+          npm run build --if-present
+          npm run build:doc --if-present
+
+      - name: Deploy
+        # Only deploy on release
+        if: github.event.release
+        uses: peaceiris/actions-gh-pages@373f7f263a76c20808c831209c920827a82a2847 # v3.9.3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./dist/doc

lib/appConfig.ts

@@ -17,7 +17,7 @@ export const appName = process.env.npm_package_name
 export const appVersion = process.env.npm_package_version
 export const appNameSanitized = appName.replace(/[/\\]/, '-')
 
-interface AppOptions extends BaseOptions {
+export interface AppOptions extends BaseOptions {
     /**
      * Whether to empty the output directory (`js/`)
      * @default true

lib/index.ts

@@ -4,6 +4,6 @@
  * SPDX-License-Identifier: AGPL-3.0-or-later
  */
 
-export { createAppConfig } from './appConfig.js'
-export { createBaseConfig } from './baseConfig.js'
-export { createLibConfig } from './libConfig.js'
+export { createAppConfig, type AppOptions } from './appConfig.js'
+export { createBaseConfig, type BaseOptions } from './baseConfig.js'
+export { createLibConfig, type LibraryOptions } from './libConfig.js'

lib/libConfig.ts

@@ -15,7 +15,7 @@ import { nodeExternals, type ExternalsOptions } from 'rollup-plugin-node-externa
 
 type OutputOptions = BuildOptions['rollupOptions']['output']
 
-interface LibraryOptions extends BaseOptions {
+export interface LibraryOptions extends BaseOptions {
 	/**
 	 * Options for the rollup node externals plugin
 	 *

package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nextcloud/vite-config",
-	"description": "Shared Vite config for nextcloud apps",
+	"description": "Shared Vite configuration for Nextcloud apps and libraries",
 	"author": {
 		"name": "Ferdinand Thiessen",
 		"email": "[email protected]"
@@ -22,6 +22,7 @@
 	},
 	"scripts": {
 		"build": "tsc",
+		"build:doc": "typedoc --out dist/doc lib/index.ts && touch dist/doc/.nojekyll",
 		"dev": "tsc --watch",
 		"lint": "eslint lib",
 		"lint:fix": "eslint --fix lib"
@@ -45,6 +46,7 @@
 	"devDependencies": {
 		"@nextcloud/eslint-config": "^8.3.0-beta.2",
 		"@types/node": "^20.4.5",
+		"typedoc": "^0.24.8",
 		"typescript": "^5.0.4"
 	},
 	"files": [