New: Static docs builds without app startup (fixes #47)

bin/docgen.js

@@ -2,7 +2,8 @@
 /**
  * Generates documentation for the installed modules.
  */
-import { App } from 'adapt-authoring-core'
+import { readJson } from 'adapt-authoring-core'
+import { loadDependencies, loadConfigDefaults, loadSchemas, loadErrors, buildRouterTree, buildPermissions } from '../lib/docsData.js'
 import docsify from '../docsify/docsify.js'
 import fs from 'fs/promises'
 import jsdoc3 from '../jsdoc3/jsdoc3.js'
@@ -11,10 +12,13 @@ import swagger from '../swagger/swagger.js'
 
 const DEBUG = process.argv.includes('--verbose')
 
-process.env.NODE_ENV ??= 'production'
-process.env.ADAPT_AUTHORING_LOGGER__mute = !DEBUG
+function getArg (name) {
+  const idx = process.argv.indexOf(name)
+  return idx !== -1 && idx + 1 < process.argv.length ? process.argv[idx + 1] : undefined
+}
+
+const rootDir = path.resolve(getArg('--rootDir') || process.cwd())
 
-const app = App.instance
 let outputdir
 
 const defaultPages = { // populated in cacheConfigs
@@ -27,10 +31,10 @@ const defaultPages = { // populated in cacheConfigs
 * Documentation for a module can be enabled in:
 * package.json > adapt_authoring.documentation.enable
 */
-function cacheConfigs () {
+function cacheConfigs (appData) {
   const cache = []
-  const excludes = app.pkg.documentation.excludes ?? []
-  Object.values(app.dependencies).forEach(dep => {
+  const excludes = appData.pkg.documentation.excludes ?? []
+  Object.values(appData.dependencies).forEach(dep => {
     const c = dep.documentation
 
     let omitMsg
@@ -49,16 +53,16 @@ function cacheConfigs () {
       ...c,
       name: dep.name,
       version: dep.version,
-      module: !!app.dependencyloader.instances[dep.name],
+      module: dep.module !== false,
       rootDir: dep.rootDir,
       includes: c.includes || {}
     })
   })
   cache.push({
-    ...app.pkg.documentation,
+    ...appData.pkg.documentation,
     enable: true,
     name: 'adapt-authoring',
-    rootDir: app.rootDir,
+    rootDir: appData.rootDir,
     includes: {}
   })
   return cache
@@ -71,29 +75,41 @@ async function copyRootFiles () {
 }
 
 async function docs () {
-  console.log(`Generating documentation for ${app.pkg.name}@${app.pkg.version} ${DEBUG ? ' :: DEBUG' : ''}`)
+  const dependencies = await loadDependencies(rootDir)
+  const pkg = { ...await readJson(path.join(rootDir, 'package.json')), ...await readJson(path.join(rootDir, 'adapt-authoring.json')) }
+  const config = await loadConfigDefaults(dependencies)
+  const schemas = await loadSchemas(dependencies)
+  const errors = await loadErrors(dependencies)
+  const routerTree = await buildRouterTree(dependencies)
+  const permissions = buildPermissions(routerTree)
 
-  try {
-    await app.onReady()
-  } catch (e) {
-    console.log(`App failed to start, cannot continue.\n${e}`)
-    process.exit(1)
+  const appData = {
+    rootDir,
+    pkg,
+    dependencies,
+    config,
+    errors,
+    schemas,
+    routerTree,
+    permissions
   }
-  const config = await app.waitForModule('config')
+
+  console.log(`Generating documentation for ${appData.pkg.name}@${appData.pkg.version} ${DEBUG ? ' :: DEBUG' : ''}`)
+
   const { name } = JSON.parse(await fs.readFile(new URL('../package.json', import.meta.url)))
-  outputdir = path.resolve(process.cwd(), config.get(`${name}.outputDir`))
+  outputdir = path.resolve(process.cwd(), getArg('--outputDir') || appData.config.get(`${name}.outputDir`))
 
-  const cachedConfigs = cacheConfigs()
+  const cachedConfigs = cacheConfigs(appData)
 
   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, defaultPages)
-    await docsify(app, cachedConfigs, outputdir, defaultPages)
-    await swagger(app, cachedConfigs, outputdir)
+    await jsdoc3(appData, cachedConfigs, outputdir, defaultPages)
+    await docsify(appData, cachedConfigs, outputdir, defaultPages)
+    await swagger(appData, cachedConfigs, outputdir)
   } catch (e) {
     console.log(e)
     process.exit(1)

bin/docserve.js

@@ -1,51 +1,39 @@
 #!/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`)
+ * Generates an HTTP server for viewing the local copy of the documentation (note these must be built 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'
+
+function getArg (name) {
+  const idx = process.argv.indexOf(name)
+  return idx !== -1 && idx + 1 < process.argv.length ? process.argv[idx + 1] : undefined
 }
-*/
-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
+async function getOutputDir () {
+  const arg = getArg('--outputDir')
+  if (arg) return path.resolve(arg)
+  const { loadDependencies, loadConfigDefaults } = await import('../lib/docsData.js')
+  const rootDir = path.resolve(getArg('--rootDir') || process.cwd())
+  const dependencies = await loadDependencies(rootDir)
+  const config = await loadConfigDefaults(dependencies)
+  return path.resolve(config.get('adapt-authoring-docs.outputDir'))
+}
 
-  const ROOT = path.resolve(app.config.get('adapt-authoring-docs.outputDir'))
-  const PORT = 9000
-  const OPEN = process.argv.some(a => a === '--open')
+const ROOT = await getOutputDir()
+const PORT = Number(getArg('--port')) || 9000
+const OPEN = process.argv.some(a => a === '--open')
 
-  const server = http.createServer({ root: ROOT, cache: -1 })
+const server = http.createServer({ root: ROOT, cache: -1 })
 
-  server.listen(PORT, () => {
-    const url = `http://localhost:${PORT}`
-    console.log(`Docs hosted at ${url}`)
+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))
-    }
-  })
+  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))
+  }
 })

docsify/docsify.js

@@ -20,9 +20,9 @@ function generateSectionTitle (sectionName) {
 /**
  * Copies all doc files ready for the generator
  */
-export default async function docsify (app, configs, outputdir, defaultPages) {
+export default async function docsify (appData, configs, outputdir, defaultPages) {
   const dir = path.resolve(outputdir, 'manual')
-  const sectionsConf = app.config.get('adapt-authoring-docs.manualSections')
+  const sectionsConf = appData.config.get('adapt-authoring-docs.manualSections')
   const defaultSection = Object.entries(sectionsConf).find(([, data]) => data.default)?.[0]
   /**
    * init docsify folder
@@ -39,7 +39,7 @@ export default async function docsify (app, configs, outputdir, defaultPages) {
         try {
           const wrapper = await new DocsifyPluginWrapper({
             ...c,
-            app,
+            app: appData,
             docsRootDir: outputdir,
             pluginEntry: path.resolve(c.rootDir, p),
             outputDir: dir

jsdoc3/jsdoc3.js

@@ -14,7 +14,7 @@ function resolvePath (relativePath) {
   return fileURLToPath(new URL(relativePath, import.meta.url))
 }
 
-async function writeConfig (app, outputdir, indexFile) {
+async function writeConfig (appData, outputdir, indexFile) {
   return fs.writeFile(configPath, JSON.stringify({
     source: {
       include: getSourceIncludes(indexFile)
@@ -25,7 +25,7 @@ async function writeConfig (app, outputdir, indexFile) {
       search: true,
       static: true,
       menu: {
-        [`<img class="logo" src="assets/logo-outline-colour.png" />Adapt authoring tool back-end API documentation<br><span class="version">v${app.pkg.version}</span>`]: {
+        [`<img class="logo" src="assets/logo-outline-colour.png" />Adapt authoring tool back-end API documentation<br><span class="version">v${appData.pkg.version}</span>`]: {
           class: 'menu-title'
         },
         'Documentation home': {
@@ -60,7 +60,7 @@ async function writeConfig (app, outputdir, indexFile) {
       meta: {
         title: 'Adapt authoring tool UI documentation',
         description: 'Adapt authoring tool UI documentation',
-        keyword: `v${app.pkg.version}`
+        keyword: `v${appData.pkg.version}`
       },
       scripts: [
         'styles/adapt.css',
@@ -88,10 +88,10 @@ function getSourceIncludes (indexFile) {
   return includes
 }
 
-export default async function jsdoc3 (app, configs, outputdir, defaultPages) {
+export default async function jsdoc3 (appData, configs, outputdir, defaultPages) {
   cachedConfigs = configs
   const dir = `${outputdir}/backend`
-  await writeConfig(app, dir, defaultPages.sourceIndex)
+  await writeConfig(appData, dir, defaultPages.sourceIndex)
   try {
     await execPromise(`npx jsdoc -c ${configPath}`)
   } catch (e) {