adapt-authoring-docs 1.0.0 → 1.1.1

package/.github/workflows/new.yml

@@ -1,19 +1,15 @@
-name: Add to main project
+# Calls the org-level reusable workflow to add PRs to the TODO Board
+
+name: Add PR to Project
 
 on:
-  issues:
-    types:
-      - opened
   pull_request:
     types:
       - opened
+      - reopened
 
 jobs:
   add-to-project:
-    name: Add to main project
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/add-to-project@v0.1.0
-        with:
-          project-url: https://github.com/orgs/adapt-security/projects/5
-          github-token: ${{ secrets.PROJECTS_SECRET }}
+    uses: adapt-security/.github/.github/workflows/new.yml@main
+    secrets:
+      PROJECTS_SECRET: ${{ secrets.PROJECTS_SECRET }}

package/adapt-authoring.json

@@ -3,9 +3,11 @@
   "documentation": {
     "enable": true,
     "manualPages": {
-      "building-docs.md": "basics",
-      "custom-documentation-plugins.md": "advanced",
-      "writing-documentation.md": "contributing"
+      "building-docs.md": "documentation",
+      "custom-documentation-plugins.md": "documentation",
+      "jsdoc-guide.md": "documentation",
+      "rest-api-guide.md": "documentation",
+      "writing-documentation.md": "documentation"
     }
   }
 }

package/bin/docgen.js

@@ -9,8 +9,10 @@ import jsdoc3 from '../jsdoc3/jsdoc3.js'
 import path from 'path'
 import swagger from '../swagger/swagger.js'
 
+const DEBUG = process.argv.includes('--verbose')
+
 process.env.NODE_ENV ??= 'production'
-process.env.ADAPT_AUTHORING_LOGGER__mute = true
+process.env.ADAPT_AUTHORING_LOGGER__mute = !DEBUG
 
 const app = App.instance
 let outputdir
@@ -68,7 +70,7 @@ async function copyRootFiles () {
 }
 
 async function docs () {
-  console.log(`Generating documentation for ${app.pkg.name}@${app.pkg.version}`)
+  console.log(`Generating documentation for ${app.pkg.name}@${app.pkg.version} ${DEBUG ? ' :: DEBUG' : ''}`)
 
   try {
     await app.onReady()

package/docs/jsdoc-guide.md

@@ -0,0 +1,196 @@
+# JSDoc style guide
+
+This guide covers the JSDoc conventions used throughout the Adapt authoring tool. Following these conventions ensures your code integrates properly with the auto-generated documentation. For comprehensive JSDoc documentation, see the [official JSDoc website](https://jsdoc.app/).
+
+The documentation generator scans all `.js` files in `lib/` and the module's `index.js`.
+
+## Basic structure
+
+All exported classes, functions, and significant variables should have JSDoc comments. Comments use the `/** ... */` format:
+
+```javascript
+/**
+ * Brief description of what this does
+ * @memberof namespaceName
+ */
+class MyClass {
+  // ...
+}
+```
+
+## Common tags reference
+
+The below table lists the most common tags used in JSDoc comments:
+
+| Tag | Purpose | Example |
+| --- | ------- | ------- |
+| `@memberof` | Assign to namespace | `@memberof core` |
+| `@extends` | Document inheritance | `@extends {AbstractModule}` |
+| `@type` | Property type | `@type {String}` |
+| `@param` | Function parameter | `@param {Object} data The input data` |
+| `@return` | Return value | `@return {Promise} Resolves with result` |
+| `@override` | Overridden method | `@override` |
+| `@typedef` | Custom type definition | `@typedef {Object} MyOptions` |
+| `@property` | Property of typedef | `@property {String} name The name` |
+| `@ignore` | Exclude from docs | `@ignore` |
+| `@example` | Code example | `@example myFunction()` |
+| `@see` | Cross-reference | `@see {ApiRoute}` |
+
+## Style notes
+
+Following [Standard.js](https://standardjs.com/) conventions:
+
+- No semicolons in examples
+- No trailing commas
+- Use single quotes in code examples
+- Two-space indentation
+
+## Namespaces
+
+Use `@memberof` to group related classes into namespaces. The namespace should use the name of your module (e.g. `core`, `api`).
+
+```javascript
+/**
+ * Core functionality
+ * @namespace core
+ */
+
+/**
+ * The main application class
+ * @memberof core
+ * @extends {AbstractModule}
+ */
+class App extends AbstractModule {
+  // ...
+}
+```
+
+## Classes
+
+Document classes with a brief description, namespace membership, and inheritance:
+
+```javascript
+/**
+ * Abstract module for creating APIs
+ * @memberof api
+ * @extends {AbstractModule}
+ */
+class AbstractApiModule extends AbstractModule {
+  // ...
+}
+```
+
+## Properties
+
+Document instance properties with `@type`. 
+
+**Important:** Any declared instance variables must be initialised to be picked up by the documentation generator. Use `undefined` if no initial value is needed.
+
+```javascript
+constructor () {
+  /**
+   * Reference to the main app instance
+   * @type {App}
+   */
+  this.app = app
+
+  /**
+   * Time taken in milliseconds for module to initialise
+   * @type {Number}
+   */
+  this.initTime = undefined  // initialise even if no value yet
+}
+```
+
+## Methods
+
+Document methods with a description, parameters, and return values:
+
+```javascript
+/**
+ * Enables waiting for other modules to load
+ * @param {...String} modNames Names of modules to wait for
+ * @return {Promise} Resolves when specified module has been loaded
+ */
+async waitForModule (...modNames) {
+  // ...
+}
+```
+
+For methods with complex parameters:
+
+```javascript
+/**
+ * Inserts a new document into the DB
+ * @param {Object} data Data to be inserted into the DB
+ * @param {InsertOptions} options Function options
+ * @param {external:MongoDBInsertOneOptions} mongoOptions Options passed to MongoDB
+ * @return {Promise} Resolves with DB data
+ */
+async insert (data, options = {}, mongoOptions = {}) {
+  // ...
+}
+```
+
+## Overridden methods
+
+Use `@override` for methods that override a parent class:
+
+```javascript
+/** @override */
+async init () {
+  await super.init()
+  // ...
+}
+```
+
+## Type definitions
+
+For complex types used across multiple files, it is recommended that you create a dedicated `typedefs.js` file. Use `@typedef` for object shapes and `@property` for each field.
+
+```javascript
+/**
+ * This file exists to define types for documentation purposes.
+ */
+
+/**
+ * Options for insert operations
+ * @memberof api
+ * @typedef {Object} InsertOptions
+ * @property {String} schemaName Name of the schema to validate against
+ * @property {String} collectionName DB collection to insert document into
+ * @property {Boolean} validate Whether incoming data should be validated
+ * @property {Boolean} invokePostHook Whether to invoke the post-action hook
+ */
+```
+
+## Excluding from documentation
+
+Use `@ignore` to exclude internal properties or methods from the generated documentation:
+
+```javascript
+/** @ignore */
+this._isReady = false
+
+/** @ignore */
+_internalMethod () {
+  // ...
+}
+```
+
+## Examples in documentation
+
+Use `@example` to include code samples:
+
+```javascript
+/**
+ * Uses default configuration for API routes
+ * @example
+ * POST /
+ * GET /:_id?
+ * PUT/DELETE /:_id
+ */
+useDefaultRouteConfig () {
+  // ...
+}
+```

package/docs/rest-api-guide.md

@@ -0,0 +1,291 @@
+# API documentation guide
+
+The Adapt authoring tool automatically generates REST API documentation using the OpenAPI 3.0 specification, rendered with Swagger UI.
+
+This guide covers how to ensure your API routes are properly documented.
+
+## Automatic documentation
+
+If your module extends `AbstractApiModule` and uses `useDefaultRouteConfig()`, documentation is generated automatically for standard CRUD routes. This generates documentation for:
+
+| Method | Route | Description |
+| ------ | ----- | ----------- |
+| POST | `/api/myresource` | Insert a new document |
+| GET | `/api/myresource` | Retrieve all documents |
+| GET | `/api/myresource/:_id` | Retrieve a single document |
+| PUT | `/api/myresource/:_id` | Replace a document |
+| PATCH | `/api/myresource/:_id` | Update a document |
+| DELETE | `/api/myresource/:_id` | Delete a document |
+| POST | `/api/myresource/query` | Query documents |
+| GET | `/api/myresource/schema` | Retrieve the schema |
+
+## Custom route metadata
+
+For custom routes, provide metadata using the `meta` property on your route definition. The metadata follows the [OpenAPI 3.0 Operation Object](https://spec.openapis.org/oas/v3.0.3#operation-object) specification.
+
+### Basic example
+
+```javascript
+async setValues () {
+   this.routes.push({
+    // ... route config
+    meta: {
+      post: {
+        summary: 'Publish a resource'
+      }
+    }
+  })
+}
+```
+
+### Defining API metadata separately
+
+For more complex APIs, define metadata in a separate file to keep your module code clean:
+
+```javascript
+// lib/apidefs.js
+export default {
+  publish: {
+    post: {
+      summary: 'Publish a resource',
+      parameters: [
+        { name: '_id', in: 'path', description: 'Resource _id', required: true }
+      ],
+      responses: {
+        200: {
+          description: 'The published resource',
+          content: {
+            'application/json': {
+              schema: { $ref: '#/components/schemas/myresource' }
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+Then import and use it in your module:
+
+```javascript
+// lib/MyApiModule.js
+import { AbstractApiModule } from 'adapt-authoring-api'
+import apidefs from './apidefs.js'
+
+class MyApiModule extends AbstractApiModule {
+  async setValues () {
+    this.routes.push({
+      // ... route config
+      meta: apidefs.publish
+    })
+  }
+}
+```
+
+## Metadata structure
+
+Each HTTP method on a route can have the following metadata:
+
+| Property | Type | Description |
+| -------- | ---- | ----------- |
+| `summary` | String | Brief description shown in the route list |
+| `description` | String | Detailed description shown when expanded |
+| `parameters` | Array | Path, query, or header parameters |
+| `requestBody` | Object | Request body schema |
+| `responses` | Object | Response schemas keyed by status code |
+
+### Parameters
+
+Define parameters for path variables, query strings, or headers:
+
+```javascript
+parameters: [
+  {
+    name: '_id',
+    // where the parameter is set: in the path (URL), as a query parameter,
+    // or as an HTTP header
+    in: 'path', 
+    description: 'The resource ID',
+    required: true
+  },
+  {
+    name: 'includeRelated',
+    in: 'query',
+    description: 'Whether to include related resources'
+  }
+]
+```
+
+### Request body
+
+Define the expected request body:
+
+```javascript
+requestBody: {
+  description: 'The resource data',
+  content: {
+    'application/json': {
+      schema: { $ref: '#/components/schemas/myresource' }
+    }
+  }
+}
+```
+
+For inline schemas:
+
+```javascript
+requestBody: {
+  content: {
+    'application/json': {
+      schema: {
+        type: 'object',
+        properties: {
+          name: { type: 'string' },
+          version: { type: 'string' },
+          force: { type: 'boolean', default: false }
+        }
+      }
+    }
+  }
+}
+```
+
+### Responses
+
+Define possible responses:
+
+```javascript
+responses: {
+  200: {
+    description: 'Successful response',
+    content: {
+      'application/json': {
+        schema: { $ref: '#/components/schemas/myresource' }
+      }
+    }
+  },
+  404: {
+    description: 'Resource not found'
+  }
+}
+```
+
+For array responses:
+
+```javascript
+responses: {
+  200: {
+    description: 'List of resources',
+    content: {
+      'application/json': {
+        schema: {
+          type: 'array',
+          items: { $ref: '#/components/schemas/myresource' }
+        }
+      }
+    }
+  }
+}
+```
+
+## Schema references
+
+Use `$ref` to reference schemas registered with the `jsonschema` module:
+
+```javascript
+{ $ref: '#/components/schemas/myresource' }
+```
+
+The schema name should match what you registered via `jsonschema.registerSchema()` or defined in a `.schema.json` file.
+
+## Complete example
+
+Here's a complete example showing custom routes with full metadata:
+
+```javascript
+// lib/apidefs.js
+export default {
+  install: {
+    post: {
+      summary: 'Install a new plugin',
+      requestBody: {
+        content: {
+          'application/json': {
+            schema: {
+              type: 'object',
+              properties: {
+                name: { type: 'string' },
+                version: { type: 'string' },
+                force: { type: 'boolean', default: false }
+              }
+            }
+          }
+        }
+      },
+      responses: {
+        200: {
+          description: 'The installed plugin',
+          content: {
+            'application/json': {
+              schema: { $ref: '#/components/schemas/contentplugin' }
+            }
+          }
+        }
+      }
+    }
+  },
+  uses: {
+    get: {
+      summary: 'Get courses using this plugin',
+      parameters: [
+        { name: '_id', in: 'path', description: 'Plugin _id', required: true }
+      ],
+      responses: {
+        200: {
+          description: 'List of courses',
+          content: {
+            'application/json': {
+              schema: {
+                type: 'array',
+                items: { $ref: '#/components/schemas/course' }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+```javascript
+// lib/MyPluginModule.js
+import { AbstractApiModule } from 'adapt-authoring-api'
+import apidefs from './apidefs.js'
+
+class MyPluginModule extends AbstractApiModule {
+  async setValues () {
+    this.root = 'plugins'
+    this.collectionName = 'plugins'
+    this.schemaName = 'plugin'
+    this.useDefaultRouteConfig()
+
+    this.routes.push(
+      {
+        route: '/install',
+        handlers: { post: this.installHandler.bind(this) },
+        permissions: { post: ['install:plugin'] },
+        validate: false,
+        meta: apidefs.install
+      },
+      {
+        route: '/:_id/uses',
+        handlers: { get: this.usesHandler.bind(this) },
+        permissions: { get: ['read:plugin'] },
+        meta: apidefs.uses
+      }
+    )
+  }
+}
+```

package/docs/writing-documentation.md

@@ -1,55 +1,59 @@
 # Writing documentation
-The Adapt authoring tool makes use of automatically generated documentation (powered by [JSDoc](https://jsdoc.app/)).
 
-**Source code reference** *mandatory* <br>
-Requires annotated code (see below), but otherwise completely automated.
+The Adapt authoring tool uses a three-tier documentation system:
 
-**Developer manual** *optional*<br>
-Requires handwritten markdown. Provides extra advice on using your code in practical scenarios.
+1. **Source code reference** — Auto-generated API documentation from JSDoc comments
+2. **Developer manual** — Handwritten markdown guides for practical usage
+3. **REST API reference** — Auto-generated OpenAPI/Swagger documentation from route definitions
 
-## Documenting code
-The source code reference is completely automated, and shouldn't need much input from you as a developer (provided your code has been correctly annotated).
+All documentation is built using the `at-docgen` CLI provided by this module.
 
-If you're not familiar with the JSDoc notation, you can find a list of accepted tags as well as examples of usage in the [JSDoc docs](https://jsdoc.app/) (you can also of course check the source code for any of the [core-supported Adapt authoring modules](coreplugins.html) which are fully documented).
+## Source code reference
 
-### Useful tips
-Below are some useful tips/gotchas for any budding documentation writers.
+JSDoc comments in your code are automatically parsed and rendered as API documentation. This requires no extra configuration beyond enabling documentation for your module, which can done by adding the following to your module's `adapt-authoring.json`:
 
-#### Instance variables must be initialised
-Any declared instance variables must be initialised in order to be picked up by the documentation generator, even if they don't need a value (in which case `this.var = undefined` is fine).
-
-## Writing developer guides
-Developer guides go a step further than the source code reference, and provide more user-friendly "how-to" guides on how to actually *use* your code in a practical scenario.
+```json
+{
+  "documentation": {
+    "enable": true
+  }
+}
+```
 
-Whether or not you include these in your modules is completely up to you, but it will greatly help the community if you do!
+For guidance on writing effective JSDoc comments, see the [JSDoc style guide](jsdoc-guide.md).
 
-What to include in developer guides:
-- Any required configuration options
-- Common usage examples
-- Any known issues/workarounds
+## Developer manual
 
-> If you have need to generate a dynamic documentation file, check out our guide on [writing custom doc plugins](custom-documentation-plugins).
+Markdown files in your module's `docs/` folder are included in the developer manual. These provide practical guides on using your module.
 
-## Configuration
-In addition to writing the manual files, you'll also need to add some configuration to the `adapt-authoring.json` file for your module to ensure that your files are included when the documentation is built.
+To assign pages to specific sections in the manual, use the `manualPages` option:
 
-All documentation-related options are contained in a `documentation` object at the root level:
 ```json
 {
   "documentation": {
     "enable": true,
-    "manualPlugins": [],
-    "manualPages": {}
+    "manualPages": {
+      "getting-started.md": "basics",
+      "advanced-usage.md": "advanced"
+    }
   }
 }
 ```
 
-The below table gives a brief explanation of each option:
+Available sections include `basics`, `advanced`, `reference`, and `contributing`. You can also define custom sections if needed. Files not listed in `manualPages` are assigned to the default section.
+
+## REST API reference
+
+You can also add documentation for the REST API endpoints defined in your module.
+
+If your module extends `AbstractApiModule`, REST API documentation is generated automatically from your route definitions. For custom routes or additional metadata, see the [API documentation guide](api-documentation.md).
+
+## Custom dynamic documentation
+
+For documentation that needs to be generated programmatically (e.g. listing all registered schemas), you can write custom documentation plugins. See [writing custom documentation plugins](custom-documentation-plugins.md) for details.
 
-| Attribute | Type | Default | Description |
-| --------- | ---- | :-----: | ----------- |
-| `enable` | Boolean | `true` | Whether documentation should be generated for this module. |
-| `manualPlugins` | Array | `[]` | A list of paths to any custom manual plugins. See [this page](custom-documentation-plugins) for more info. |
-| `manualPages` | Object | `{}` | A key/value store mapping file names to a section (e.g. `"manual-page.md": "advanced"`). The key must be the filename only, and not a path. The section ID must match one of those defined in the config (see the [configuration reference](configuration?id=adapt-authoring-docs) for the defaults, or set your own in your config file). |
+## Further reading
 
-> You can also store manual files in the root repository of the application; just make sure to add your doc files to a `/docs` directory.
+- [JSDoc style guide](jsdoc-guide.md) — Conventions for documenting your code
+- [API documentation guide](api-documentation.md) — Documenting REST API endpoints
+- [Custom documentation plugins](custom-documentation-plugins.md) — Generating dynamic documentation

package/docsify/styles/adapt.css

@@ -188,6 +188,7 @@ ul.toc > li {
 .attribute .default pre {
   display: inline;
   padding: 0 5px;
+  background: transparent;
 }
 .markdown-section table.schema {
   margin-top: 25px;
@@ -227,4 +228,4 @@ body.dark .markdown-section tr:nth-child(2n) {
 body.dark .markdown-section blockquote {
   background: #004a32;
   color: inherit;
-}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "adapt-authoring-docs",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "description": "Tools for auto-generating documentation for the Adapt authoring tool",
   "homepage": "https://github.com/adapt-security/adapt-authoring-docs",
   "license": "GPL-3.0",
@@ -15,7 +15,7 @@
     "docdash": "^2.0.2",
     "docsify-cli": "^4.4.4",
     "fs-extra": "^11.2.0",
-    "glob": "^11.0.0",
+    "glob": "^13.0.0",
     "http-server": "^14.1.1",
     "jsdoc": "^4.0.3",
     "swagger-ui": "^5.17.14"

package/.github/workflows/labelled_prs.yml

@@ -1,16 +0,0 @@
-name: Add labelled PRs to project
-
-on:
-  pull_request:
-    types: [ labeled ]
-
-jobs:
-  add-to-project:
-    if: ${{ github.event.label.name == 'dependencies' }}
-    name: Add to main project
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/add-to-project@v0.1.0
-        with:
-          project-url: https://github.com/orgs/adapt-security/projects/5
-          github-token: ${{ secrets.PROJECTS_SECRET }}