adapt-authoring-docs 0.0.1

package/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,55 @@
+name: Bug Report
+description: File a bug report
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to fill out this bug report!
+  - type: textarea
+    id: description
+    attributes:
+      label: What happened?
+      description: Please describe the issue
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behaviour
+      description: Tell us what should have happened
+  - type: textarea
+    id: repro-steps
+    attributes:
+      label: Steps to reproduce
+      description: Tell us how to reproduce the issue
+    validations:
+      required: true
+  - type: input
+    id: aat-version
+    attributes:
+      label: Authoring tool version
+      description: What version of the Adapt authoring tool are you running?
+    validations:
+      required: true
+  - type: input
+    id: fw-version
+    attributes:
+      label: Framework version
+      description: What version of the Adapt framework are you running?
+  - type: dropdown
+    id: browsers
+    attributes:
+      label: What browsers are you seeing the problem on?
+      multiple: true
+      options:
+        - Firefox
+        - Chrome
+        - Safari
+        - Microsoft Edge
+  - type: textarea
+    id: logs
+    attributes:
+      label: Relevant log output
+      description: Please copy and paste any relevant log output. This will be automatically formatted into code, so no need for backticks.
+      render: sh

package/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1 @@
+blank_issues_enabled: false

package/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,22 @@
+name: Feature request
+description: Request a new feature
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to request a new feature in the Adapt authoring tool! The Adapt team will consider all new feature requests, but unfortunately cannot commit to every one.
+  - type: textarea
+    id: description
+    attributes:
+      label: Feature description
+      description: Please describe your feature request
+    validations:
+      required: true
+  - type: checkboxes
+    id: contribute
+    attributes:
+      label: Can you work on this feature?
+      description: If you are able to commit your own time to work on this feature, it will greatly increase the liklihood of it being implemented by the core dev team. Otherwise, it will be triaged and prioritised alongside the core team's current priorities.
+      options:
+        - label: I can contribute

package/.github/dependabot.yml

@@ -0,0 +1,11 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://docs.github.com/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
+
+version: 2
+updates:
+  - package-ecosystem: "npm" # See documentation for possible values
+    directory: "/" # Location of package manifests
+    schedule:
+      interval: "weekly"

package/.github/pull_request_template.md

@@ -0,0 +1,25 @@
+[//]: # (Please title your PR according to eslint commit conventions)
+[//]: # (See https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-eslint#eslint-convention for details)
+
+[//]: # (Add a link to the original issue)
+
+[//]: # (Delete as appropriate)
+### Fix
+* A sentence describing each fix
+
+### Update
+* A sentence describing each udpate
+
+### New
+* A sentence describing each new feature
+
+### Breaking
+* A sentence describing each breaking change
+
+[//]: # (List appropriate steps for testing if needed)
+### Testing
+1. Steps for testing
+
+[//]: # (Mention any other dependencies)
+
+

package/.github/workflows/labelled_prs.yml

@@ -0,0 +1,16 @@
+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 }}

package/.github/workflows/new.yml

@@ -0,0 +1,19 @@
+name: Add to main project
+
+on:
+  issues:
+    types:
+      - opened
+  pull_request:
+    types:
+      - opened
+
+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 }}

package/.github/workflows/releases.yml

@@ -0,0 +1,32 @@
+name: Release
+on:
+  push:
+    branches:
+      - master
+
+jobs:
+  release:
+    name: Release
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write # to be able to publish a GitHub release
+      issues: write # to be able to comment on released issues
+      pull-requests: write # to be able to comment on released pull requests
+      id-token: write # to enable use of OIDC for trusted publishing and npm provenance
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+      - name: Setup Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: 'lts/*'
+      - name: Update npm
+        run: npm install -g npm@latest
+      - name: Install dependencies
+        run: npm ci
+      - name: Release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: npx semantic-release

package/.github/workflows/standardjs.yml

@@ -0,0 +1,13 @@
+name: Standard.js formatting check
+on: push
+jobs:
+  default:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@master
+      - uses: actions/setup-node@master
+        with:
+          node-version: 'lts/*'
+          cache: 'npm'
+      - run: npm ci
+      - run: npx standard

package/adapt-authoring.json

@@ -0,0 +1,11 @@
+{
+  "module": false,
+  "documentation": {
+    "enable": true,
+    "manualPages": {
+      "building-docs.md": "basics",
+      "custom-documentation-plugins.md": "advanced",
+      "writing-documentation.md": "contributing"
+    }
+  }
+}

package/bin/docgen.js

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+/**
+ * Generates documentation for the installed modules.
+ */
+import { App } from 'adapt-authoring-core'
+import docsify from '../docsify/docsify.js'
+import fs from 'fs/promises'
+import jsdoc3 from '../jsdoc3/jsdoc3.js'
+import path from 'path'
+import swagger from '../swagger/swagger.js'
+
+process.env.NODE_ENV ??= 'production'
+process.env.ADAPT_AUTHORING_LOGGER__mute = true
+
+const app = App.instance
+let outputdir
+
+let manualIndex // populated in cacheConfigs
+let sourceIndex // populated in cacheConfigs
+/**
+* Caches loaded JSON so we don't load multiple times.
+* Documentation for a module can be enabled in:
+* package.json > adapt_authoring.documentation.enable
+*/
+function cacheConfigs () {
+  const cache = []
+  const excludes = app.pkg.documentation.excludes ?? []
+  Object.values(app.dependencies).forEach(dep => {
+    const c = dep.documentation
+
+    let omitMsg
+    if (!c) omitMsg = 'no documentation config defined'
+    else if (!c.enable) omitMsg = 'documentation.enable is set to false'
+    else if (excludes.includes(dep.name)) omitMsg = 'module has been excluded in documentation config'
+    if (omitMsg) return console.log(`Omitting ${dep.name}, ${omitMsg}`)
+
+    if (c.manualIndex) {
+      if (manualIndex) return console.log(`${dep.name}: manualIndex has been specified by another module as ${manualIndex}`)
+      manualIndex = path.join(dep.rootDir, c.manualIndex).split(path.sep).join(path.posix.sep)
+    }
+    if (c.sourceIndex) {
+      if (sourceIndex) return console.log(`${dep.name}: sourceIndex has been specified by another module as ${sourceIndex}`)
+      sourceIndex = path.join(dep.rootDir, c.sourceIndex).split(path.sep).join(path.posix.sep)
+    }
+    cache.push({
+      ...c,
+      name: dep.name,
+      version: dep.version,
+      module: !!app.dependencyloader.instances[dep.name],
+      rootDir: dep.rootDir,
+      includes: c.includes || {}
+    })
+  })
+  cache.push({
+    ...app.pkg.documentation,
+    enable: true,
+    name: 'adapt-authoring',
+    rootDir: app.rootDir,
+    includes: {}
+  })
+  return cache
+}
+
+async function copyRootFiles () {
+  const resolve = p => new URL(`../${p}`, import.meta.url)
+  await fs.cp(resolve('/root'), outputdir, { recursive: true })
+  await fs.cp(resolve('assets'), path.resolve(outputdir, 'assets'), { recursive: true })
+}
+
+async function docs () {
+  console.log(`Generating documentation for ${app.pkg.name}@${app.pkg.version}`)
+
+  try {
+    await app.onReady()
+  } catch (e) {
+    console.log(`App failed to start, cannot continue.\n${e}`)
+    process.exit(1)
+  }
+  const config = await app.waitForModule('config')
+  const { name } = JSON.parse(await fs.readFile(new URL('../package.json', import.meta.url)))
+  outputdir = path.resolve(process.cwd(), config.get(`${name}.outputDir`))
+
+  const cachedConfigs = cacheConfigs()
+
+  console.log('\nThis might take a minute or two...\n')
+
+  try {
+    await fs.rm(outputdir, { recursive: true, force: true })
+    await fs.mkdir(outputdir)
+    await copyRootFiles()
+    await jsdoc3(app, cachedConfigs, outputdir, sourceIndex)
+    await docsify(app, cachedConfigs, outputdir, manualIndex, sourceIndex)
+    await swagger(app, cachedConfigs, outputdir)
+  } catch (e) {
+    console.log(e)
+    process.exit(1)
+  }
+  console.log('Documentation build complete.')
+  process.exit()
+}
+
+export default docs()

package/bin/docserve.js

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+/**
+ * Generates an HTTP server for viewing the local copy of the documentation (note these must be build first with `at-docgen`)
+ */
+import { App } from 'adapt-authoring-core'
+import { spawn } from 'child_process'
+import http from 'http-server'
+import path from 'path'
+/*
+function getMime (filePath) {
+  const ext = path.parse(filePath).ext
+  return {
+    '.ico': 'image/x-icon',
+    '.html': 'text/html',
+    '.js': 'text/javascript',
+    '.json': 'application/json',
+    '.css': 'text/css',
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.svg': 'image/svg+xml',
+    '.pdf': 'application/pdf',
+    '.doc': 'application/msword'
+  }[ext] || 'text/plain'
+}
+*/
+process.env.NODE_ENV ??= 'production'
+process.env.ADAPT_AUTHORING_LOGGER__mute = true
+
+console.log('Starting app, please wait\n')
+// TODO remove need to start app
+App.instance.onReady().then(async app => {
+  console.log('App started\n');
+  (await app.waitForModule('server')).close() // close connections so we can still run the app separately
+
+  const ROOT = path.resolve(app.config.get('adapt-authoring-docs.outputDir'))
+  const PORT = 9000
+  const OPEN = process.argv.some(a => a === '--open')
+
+  const server = http.createServer({ root: ROOT, port: PORT })
+
+  server.listen(PORT, () => {
+    const url = `http://localhost:${PORT}`
+    console.log(`Docs hosted at ${url}`)
+
+    if (OPEN) {
+      const command = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open'
+      spawn(`${command} ${url}`, { shell: true })
+        .on('error', e => console.log('spawn error', e))
+    }
+  })
+})

package/conf/config.schema.json

@@ -0,0 +1,40 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "outputDir": {
+      "description": "Path to store documentation build files",
+      "type": "string",
+      "isDirectory": true,
+      "default": "$TEMP/docs-build"
+    },
+    "manualSections": {
+      "description": "Sections for categorising documentation manual pages",
+      "type": "object",
+      "default": {
+        "getting-started": {
+          "title": "Getting started"
+        },
+        "basics": {
+          "title": "The basics"
+        },
+        "advanced": {
+          "title": "Advanced topics"
+        },
+        "ui": {
+          "title": "Front-end app"
+        },
+        "other-guides": {
+          "title": "Other guides",
+          "default": true
+        },
+        "contributing": {
+          "title": "Contributing"
+        },
+        "reference": {
+          "title": "Reference"
+        }
+      }
+    }
+  }
+}

package/docs/building-docs.md

@@ -0,0 +1,21 @@
+# Building the docs
+If you want to build your own local copy of the documentation, you'll need to run the bin script bundled with the documentation module.
+
+> If you ran the automated intaller, chances are you didn't install the optional developer dependencies (and therefore don't have the documentation module). You can fix this by running:
+`npm i --only=dev`
+
+Run the documentation generator using:
+
+```bash
+npx at-docgen
+```
+
+Once the documentation has been built, it'll be stored in the temp directory. Where this is will vary depending on your config file, but you can find the default [location here](configuration?id=adapt-authoring-docs).
+
+To correctly view the docs, you'll need to run a local web server. You can do this using another automated bin script bundled with the documentation module:
+
+```bash
+npx at-docserve
+```
+
+See the [bin script docs](binscripts) for full usage details.

package/docs/custom-documentation-plugins.md

@@ -0,0 +1,41 @@
+# Writing custom documentation plugins
+
+In addition to the standard static markdown files, you can also generate dynamic content by writing your own documentation plugin.
+
+To do this, you need to do the following:
+
+## 1. Write your plugin
+The first step involves writing the Javascript to do what you need. Here are a few tips on writing your own documentation plugin:
+- Write any new `.md` files to the `outputDir` directory (any files not in this folder will not be included in the final output!)
+- Include any new files in the `customFiles` array (forgetting this step will mean your files aren't included in the documentation side nav bar)
+- You can access any App properties using the instance passed to your plugin's constructor
+- To keep things neat, we recommend putting all plugin files in a separate `plugins/` folder in the `docs/` folder of your module (e.g. `mymodule/docs/plugins/MyDocPlugin.js`)
+
+You can use the following code as a starting-point:
+```js
+class MyDocPlugin {
+  /**
+   * @param {App} app Reference to the main App instance
+   * @param {Object} config Parsed adapt-authoring.json file for this module
+   * @param {String} outputDir The docs output path (write any custom .md files here)
+   */
+  constructor(app, config, outputDir) {
+    // include the FULL paths to any new .md files in this array. 
+    this.customFiles = [];
+  }
+}
+module.exports = MyDocPlugin;
+```
+
+## 2. Add your plugin to adapt-authoring.json
+In order for your plugin to be executed by the documentation generator, you must add it to the list of `manualPlugins` in the `adapt-authoring.json` for your module (this path should be relative to the root folder of your plugin).
+
+```json
+{
+  "documentation": {
+    // ...other options
+    "manualPlugins": ["docs/plugins/MyDocPlugin.js"]
+  }
+}
+
+```

package/docs/writing-documentation.md

@@ -0,0 +1,55 @@
+# 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.
+
+**Developer manual** *optional*<br>
+Requires handwritten markdown. Provides extra advice on using your code in practical scenarios.
+
+## 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).
+
+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).
+
+### Useful tips
+Below are some useful tips/gotchas for any budding documentation writers.
+
+#### 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.
+
+Whether or not you include these in your modules is completely up to you, but it will greatly help the community if you do!
+
+What to include in developer guides:
+- Any required configuration options
+- Common usage examples
+- Any known issues/workarounds
+
+> If you have need to generate a dynamic documentation file, check out our guide on [writing custom doc plugins](custom-documentation-plugins).
+
+## 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.
+
+All documentation-related options are contained in a `documentation` object at the root level:
+```json
+{
+  "documentation": {
+    "enable": true,
+    "manualPlugins": [],
+    "manualPages": {}
+  }
+}
+```
+
+The below table gives a brief explanation of each option:
+
+| 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). |
+
+> 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.

package/docsify/DocsifyPluginWrapper.js

@@ -0,0 +1,67 @@
+import fs from 'fs'
+import path from 'path'
+import { pathToFileURL } from 'url'
+/**
+ * Utility functions to be used by Docsify plugins
+ */
+export default class DocsifyPluginWrapper {
+  get customFiles () {
+    return this.plugin.customFiles ?? []
+  }
+
+  constructor (config) {
+    this.config = config
+    this.config.srcDir = path.dirname(config.pluginEntry)
+  }
+
+  async init () {
+    const PluginClass = (await import(pathToFileURL(this.config.pluginEntry))).default
+    this.plugin = new PluginClass()
+    this.plugin.app = this.config.app
+    this.plugin.config = this.config
+
+    if (!this.plugin.run || typeof this.plugin.run !== 'function') throw new Error('Documentation plugin must define a \'run\' function')
+
+    await this.plugin.run()
+    // set some default values
+    this.plugin.contents ??= []
+    this.plugin.customFiles ??= []
+    this.plugin.replace ??= {}
+
+    if (this.plugin.manualFile) await this.writeFile()
+  }
+
+  generateTOC (items) {
+    const pageName = this.plugin?.manualFile?.replace(path.extname(this.plugin.manualFile), '') ?? ''
+    let output = '### Quick navigation\n\n<ul class="toc">\n'
+    items.forEach(i => {
+      let text = i; let link = i
+      if (Array.isArray(i)) {
+        text = i[0]
+        link = i[1]
+      }
+      output += `<li><a href="#/${pageName}?id=${link}">${text}</a></li>\n`
+    })
+    output += '</ul>\n'
+    return output
+  }
+
+  async writeFile () {
+    if (this.plugin.contents.length) {
+      this.plugin.replace.TABLE_OF_CONTENTS = this.generateTOC(this.plugin.contents)
+    }
+    const filePath = path.resolve(this.config.srcDir, this.plugin.manualFile)
+    let file
+    try {
+      file = fs.readFileSync(filePath).toString()
+    } catch (e) {
+      throw new Error(`Failed to load manual file at ${filePath}`)
+    }
+    // do any specified string replacements
+    file = Object.entries(this.plugin.replace).reduce((f, [key, value]) => f.replaceAll(`{{{${key}}}}`, value), file)
+
+    const outputPath = path.join(this.config.outputDir, this.plugin.manualFile)
+    this.plugin.customFiles.push(outputPath)
+    fs.writeFileSync(outputPath, file)
+  }
+}