chore: add jsdocs + extension docs auto-gen (#783)

* docs: add GitHub Actions workflow to trigger documentation updates on main branch changes

* chore: add ESLint configuration for JSDoc validation in documentation files

* chore: update ESLint configuration for JSDoc and enhance type definitions in field annotation

* chore: refine field annotation file structure and suppress TypeScript errors

* docs: enhance Editor type definition in SuperDoc.js for improved clarity and structure

* docs: enhance JSDoc comments for field annotation methods to improve clarity and type definitions

* chore: disable checkJs in tsconfig and enable JSDoc checking in field annotation file

* chore: remove redundant JSDoc type definitions in SuperDoc.js and clean up ESLint configuration

* chore: remove TypeScript ignore comments from various files to improve code quality

* chore: remove TypeScript ignore comments from FieldAnnotationPlugin.js to enhance code quality

* chore: refactor build scripts and remove unused TypeScript type definitions in super-editor

* chore: update build configuration and improve TypeScript output structure in super-editor

* docs: enhance JSDoc comments and type definitions for DocumentSection in super-editor

* docs: add @category Command tag to JSDoc comments in DocumentSection for better organization

* docs: refine JSDoc comments and type definitions for section creation and update in DocumentSection

* chore: remove outDir option from tsconfig.build.json in super-editor

* chore: refactor initPagination method to private and update tsconfig formatting in super-editor

* refactor: replace initPagination calls with private method #initPagination in Editor class

* fix: correct syntax in catch blocks for better error handling in Editor class

* Doc gen: Add aliases to tsconfig, remove ts-ignore in document sections  (#798)

* chore: add vite aliases to tsconfig

* fix: remove ts-ignore and fix issues to ensure file builds

---------

Co-authored-by: Caio Pizzol <caiopizzol@icloud.com>
Co-authored-by: Nick Bernal <117235294+harbournick@users.noreply.github.com>

Author: 3 people

.github/workflows/trigger-docs-update.yml

@@ -0,0 +1,35 @@
+name: Trigger Documentation Update
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      # Trigger when extensions change
+      - 'packages/super-editor/src/extensions/**/*.js'
+      # - 'packages/super-editor/src/core/**/*.js'
+      # - 'packages/super-editor/src/components/**/*.js'
+  workflow_dispatch:  # Manual trigger
+
+jobs:
+  trigger-docs:
+    runs-on: ubuntu-latest    
+    steps:
+      - name: Trigger Documentation Repository Update
+        run: |
+          # Set the required variables
+          repo_owner="Harbour-Enterprises" 
+          repo_name="SuperDoc-Docs"  
+          event_type="docs-update"
+
+          curl -L \
+            -X POST \
+            -H "Accept: application/vnd.github+json" \
+            -H "Authorization: Bearer ${{ secrets.SUPERDOC_PAT }}" \
+            -H "X-GitHub-Api-Version: 2022-11-28" \
+            https://api.github.com/repos/$repo_owner/$repo_name/dispatches \
+            -d "{\"event_type\": \"$event_type\"}"
+      
+      - name: Notify Success
+        if: success()
+        run: echo "✅ Documentation update triggered successfully"

.gitignore

@@ -10,6 +10,7 @@ dist-ssr
 .env
 .npmrc
 .eslintcache
+types/
 
 npm-debug.log*
 yarn-debug.log*

eslint.config.docs.mjs

@@ -0,0 +1,84 @@
+import jsdoc from 'eslint-plugin-jsdoc';
+
+export default [
+  {
+    files: ['packages/super-editor/src/extensions/**/*.js'],
+    plugins: {
+      jsdoc
+    },
+    rules: {
+      // Require minimal JSDoc for extensions
+      'jsdoc/require-jsdoc': ['warn', {
+        publicOnly: true,
+        require: {
+          FunctionDeclaration: false,
+          MethodDefinition: false,
+          ClassDeclaration: false,
+          ArrowFunctionExpression: false,
+          FunctionExpression: false
+        },
+        contexts: [
+          // Document the extension module
+          'ExportNamedDeclaration > VariableDeclaration > VariableDeclarator > CallExpression[callee.property.name="create"]'
+
+          // Note: We document commands/helpers with @param/@returns
+          // inside addCommands/addHelpers, not with require-jsdoc
+        ]
+      }],
+
+      // When JSDoc exists, validate it's correct
+      'jsdoc/require-param': 'error',             // All params must be documented
+      'jsdoc/require-param-type': 'error',        // @param must have {Type}
+      'jsdoc/check-param-names': 'error',         // @param names must match
+      'jsdoc/check-types': 'error',               // Valid type syntax (string not String)
+
+      // Optional - we use @returns {Function} or skip it
+      'jsdoc/require-returns': 'off',
+      'jsdoc/require-returns-type': 'off',
+
+      // Don't require descriptions if obvious
+      'jsdoc/require-param-description': 'off',
+      'jsdoc/require-returns-description': 'off',
+      'jsdoc/require-description': 'off',
+
+      // Don't require examples - nice to have but not essential
+      'jsdoc/require-example': 'off',
+
+      // Simple formatting
+      'jsdoc/require-hyphen-before-param-description': 'off', // Optional: @param {Type} name - Description
+
+      // Allow types from our .d.ts files and common types
+      'jsdoc/no-undefined-types': ['warn', {
+        definedTypes: [
+          // Allow any type that starts with capital letter (likely imported)
+          '/^[A-Z]/',
+
+          // Common utility types
+          'Partial', 'Required', 'Readonly', 'Pick', 'Omit',
+
+          // Built-in types
+          'Function', 'Object', 'Array', 'Promise',
+
+          // DOM
+          'HTMLElement', 'Element', 'Event'
+        ]
+      }],
+
+      // Don't enforce these
+      'jsdoc/valid-types': 'off',                 // We use TypeScript syntax
+      'jsdoc/check-tag-names': 'off',             // Allow @module, @typedef, etc.
+      'jsdoc/check-alignment': 'off',             // Don't worry about alignment
+      'jsdoc/multiline-blocks': 'off'             // Allow single or multi-line
+    },
+    settings: {
+      jsdoc: {
+        mode: 'typescript',      // Understand TypeScript syntax in JSDoc
+        preferredTypes: {
+          object: 'Object',      // Use Object not object
+          array: 'Array',        // Use Array not array
+          'Array.<>': 'Array<>', // Use Array<Type> not Array.<Type>
+        }
+      }
+    }
+  }
+];

package-lock.json

@@ -25,6 +25,8 @@
     "format:check": "prettier --check \"**/*.{js,jsx,vue,css,scss,json,md}\"",
     "lint": "eslint",
     "lint:fix": "eslint --fix",
+    "lint:jsdoc": "eslint packages/super-editor/src/extensions/field-annotation/field-annotation.js --config eslint.config.docs.mjs",
+    "lint:jsdoc:fix": "eslint packages/super-editor/src/extensions/field-annotation/field-annotation.js --config eslint.config.docs.mjs --fix",
     "docs:dev": "vuepress dev docs",
     "docs:build": "vuepress build docs",
     "pack": "npm run build:super-editor && npm --prefix ./packages/superdoc run pack",
@@ -54,6 +56,7 @@
     "@vuepress/theme-default": "^2.0.0-rc.60",
     "eslint": "^9.31.0",
     "eslint-config-prettier": "^9.1.0",
+    "eslint-plugin-jsdoc": "^54.1.0",
     "husky": "^9.1.7",
     "lint-staged": "^16.1.4",
     "prettier": "3.3.3",

package.json

@@ -38,11 +38,13 @@
   "module": "./dist/super-editor.es.js",
   "scripts": {
     "dev": "vite",
-    "preview": "vite preview",
-    "build": "vite build && tsc",
-    "clean": "rm -rf dist",
+    "build": "vite build && npm run types:build",
+    "build:watch": "vite build --watch",
+    "types:check": "tsc --noEmit",
+    "types:build": "tsc -p tsconfig.build.json",
     "test": "vitest",
-    "build:watch": "vite build --watch --logLevel warn",
+    "preview": "vite preview",
+    "clean": "rm -rf dist types",
     "pack": "rm *.tgz 2>/dev/null || true && npm run build && npm pack && mv harbour-enterprises-super-editor-0.0.1-alpha.0.tgz ./super-editor.tgz"
   },
   "dependencies": {