@antora/site-generator-default 3.0.0-alpha.7 → 3.0.0-beta.2

package/README.md

@@ -1,10 +1,10 @@
 # Antora Default Site Generator
 
-This is the default site generator pipeline for Antora.
-This pipeline is invoked by the `generate` command of Antora's CLI to produce and publish static documentation sites.
+This is the default site generator for Antora.
+This generator is invoked by the `generate` command of Antora's CLI to produce and publish static documentation sites.
 
 [Antora](https://antora.org) is a modular static site generator designed for creating documentation sites from AsciiDoc documents.
-Its site generator pipeline aggregates documents from versioned content repositories and processes them using [Asciidoctor](https://asciidoctor.org).
+Its site generator aggregates documents from versioned content repositories and processes them using [Asciidoctor](https://asciidoctor.org).
 
 ## Copyright and License
 

package/lib/generate-site.js

@@ -1,40 +1,65 @@
 'use strict'
 
-const aggregateContent = require('@antora/content-aggregator')
-const buildNavigation = require('@antora/navigation-builder')
-const buildPlaybook = require('@antora/playbook-builder')
-const classifyContent = require('@antora/content-classifier')
-const convertDocuments = require('@antora/document-converter')
-const createPageComposer = require('@antora/page-composer')
-const loadUi = require('@antora/ui-loader')
-const mapSite = require('@antora/site-mapper')
-const produceRedirects = require('@antora/redirect-producer')
-const publishSite = require('@antora/site-publisher')
-const { resolveAsciiDocConfig } = require('@antora/asciidoc-loader')
+const GeneratorContext = require('./generator-context')
+const SiteCatalog = require('./site-catalog')
 
-async function generateSite (args, env) {
-  const playbook = buildPlaybook(args, env)
-  const asciidocConfig = resolveAsciiDocConfig(playbook)
-  const [contentCatalog, uiCatalog] = await Promise.all([
-    aggregateContent(playbook).then((contentAggregate) => classifyContent(playbook, contentAggregate, asciidocConfig)),
-    loadUi(playbook),
-  ])
-  const pages = convertDocuments(contentCatalog, asciidocConfig)
-  const navigationCatalog = buildNavigation(contentCatalog, asciidocConfig)
-  const composePage = createPageComposer(playbook, contentCatalog, uiCatalog, env)
-  pages.forEach((page) => composePage(page, contentCatalog, navigationCatalog))
-  const siteFiles = [...mapSite(playbook, pages), ...produceRedirects(playbook, contentCatalog)]
-  if (playbook.site.url) siteFiles.push(composePage(create404Page()))
-  const siteCatalog = { getFiles: () => siteFiles }
-  return publishSite(playbook, [contentCatalog, uiCatalog, siteCatalog]).then((publications) => {
-    if (!playbook.runtime.quiet && process.stdout.isTTY) {
-      process.stdout.write('Site generation complete!\n')
-      publications.forEach(
-        ({ fileUri }) => fileUri && process.stdout.write(`View the site by visiting ${fileUri} in a browser.\n`)
-      )
+async function generateSite (playbook) {
+  const context = new GeneratorContext(module)
+  try {
+    const { fxns, vars } = await GeneratorContext.start(context, playbook)
+    await context.notify('playbookBuilt')
+    playbook = vars.lock('playbook')
+    vars.asciidocConfig = fxns.resolveAsciiDocConfig(playbook)
+    vars.siteCatalog = new SiteCatalog()
+    await context.notify('beforeProcess')
+    const asciidocConfig = vars.lock('asciidocConfig')
+    await Promise.all([
+      fxns.aggregateContent(playbook).then((contentAggregate) =>
+        context.notify('contentAggregated', Object.assign(vars, { contentAggregate })).then(() => {
+          vars.contentCatalog = fxns.classifyContent(playbook, vars.remove('contentAggregate'), asciidocConfig)
+        })
+      ),
+      fxns.loadUi(playbook).then((uiCatalog) => context.notify('uiLoaded', Object.assign(vars, { uiCatalog }))),
+    ])
+    await context.notify('contentClassified')
+    const contentCatalog = vars.lock('contentCatalog')
+    const uiCatalog = vars.lock('uiCatalog')
+    fxns.convertDocuments(contentCatalog, asciidocConfig)
+    await context.notify('documentsConverted')
+    vars.navigationCatalog = fxns.buildNavigation(contentCatalog, asciidocConfig)
+    await context.notify('navigationBuilt')
+    ;(() => {
+      const navigationCatalog = vars.remove('navigationCatalog')
+      const composePage = fxns.createPageComposer(playbook, contentCatalog, uiCatalog, playbook.env)
+      contentCatalog.getPages((page) => page.out && composePage(page, contentCatalog, navigationCatalog))
+      if (playbook.site.url) vars.siteCatalog.addFile(composePage(create404Page()))
+    })()
+    await context.notify('pagesComposed')
+    vars.siteCatalog.addFiles(fxns.produceRedirects(playbook, contentCatalog))
+    await context.notify('redirectsProduced')
+    if (playbook.site.url) {
+      const publishablePages = contentCatalog.getPages((page) => page.out)
+      vars.siteCatalog.addFiles(fxns.mapSite(playbook, publishablePages))
+      await context.notify('siteMapped')
     }
-    return publications
-  })
+    await context.notify('beforePublish')
+    return fxns.publishSite(playbook, [contentCatalog, uiCatalog, vars.lock('siteCatalog')]).then((publications) => {
+      if (!playbook.runtime.quiet && process.stdout.isTTY) {
+        process.stdout.write('Site generation complete!\n')
+        publications.forEach(
+          ({ fileUri }) => fileUri && process.stdout.write(`View the site by visiting ${fileUri} in a browser.\n`)
+        )
+      }
+      return context
+        .notify('sitePublished', Object.assign(vars, { publications }))
+        .then(() => vars.remove('publications'))
+    })
+  } catch (err) {
+    if (!GeneratorContext.isStopSignal(err)) throw err
+    await err.notify()
+  } finally {
+    await GeneratorContext.close(context)
+  }
 }
 
 function create404Page () {

package/lib/generator-context.js

@@ -0,0 +1,166 @@
+'use strict'
+
+const EventEmitter = require('events')
+const getLogger = require('@antora/logger')
+const userRequire = require('@antora/user-require-helper')
+
+const FUNCTION_PROVIDERS = {
+  aggregateContent: 'content-aggregator',
+  buildNavigation: 'navigation-builder',
+  classifyContent: 'content-classifier',
+  convertDocument: 'document-converter',
+  convertDocuments: 'document-converter',
+  createPageComposer: 'page-composer',
+  extractAsciiDocMetadata: 'asciidoc-loader',
+  loadAsciiDoc: 'asciidoc-loader',
+  loadUi: 'ui-loader',
+  mapSite: 'site-mapper',
+  produceRedirects: 'redirect-producer',
+  publishSite: 'site-publisher',
+  resolveAsciiDocConfig: 'asciidoc-loader',
+}
+
+const FUNCTION_WITH_POSITIONAL_PARAMETER_RX = /^(?:function *)?(?:\w+ *)?\( *\w|^\w+(?: *, *\w+)* *=>/
+const NEWLINES_RX = /\r?\n/g
+
+class StopSignal extends Error {}
+
+class GeneratorContext extends EventEmitter {
+  #fxns
+  #vars
+
+  constructor (module_) {
+    super()
+    // deprecated method aliases - remove for Antora 3.0.0
+    Object.defineProperties(this, { halt: { value: this.stop }, updateVars: { value: this.updateVariables } })
+    if (!('path' in (this.module = module_))) module_.path = require('path').dirname(module_.filename)
+  }
+
+  getFunctions () {
+    return arguments.length ? this.#fxns : Object.assign({}, this.#fxns)
+  }
+
+  getLogger (name = 'antora') {
+    return getLogger(name)
+  }
+
+  getVariables () {
+    return Object.assign({}, this.#vars)
+  }
+
+  async notify (eventName) {
+    if (!this.listenerCount(eventName)) return
+    for (const listener of this.rawListeners(eventName)) {
+      const outcome = listener.length === 1 ? listener.call(this, this.getVariables()) : listener.call(this)
+      if (outcome instanceof Promise) await outcome
+    }
+  }
+
+  replaceFunctions (updates) {
+    const fxns = this.#fxns
+    Object.entries(updates).forEach(([name, fxn]) => {
+      if (name in fxns) fxns[name] = fxn.bind(this)
+    })
+  }
+
+  require (request) {
+    return this.module.require(request)
+  }
+
+  stop (code) {
+    if (code != null) process.exitCode = code
+    throw Object.assign(new StopSignal(), { notify: this.notify.bind(this, 'contextStopped') })
+  }
+
+  updateVariables (updates) {
+    try {
+      Object.assign(this.#vars, updates)
+    } catch (err) {
+      if (err instanceof TypeError) {
+        err.message = err.message.replace(/ assign to read.only property '(.+)' .*/, " update read-only var '$1'")
+      }
+      throw err
+    }
+  }
+
+  static async close (instance) {
+    await instance.notify('contextClosed').catch(() => undefined)
+  }
+
+  static isStopSignal (err) {
+    return err instanceof StopSignal
+  }
+
+  static async start (instance, playbook) {
+    const returnValue = instance._init(playbook)
+    await instance.notify('contextStarted')
+    return returnValue
+  }
+
+  _init (playbook) {
+    this._registerFunctions()
+    this._registerExtensions(playbook, this._initVariables(playbook))
+    Object.defineProperties(this, { _init: {}, _initVariables: {}, _registerExtensions: {}, _registerFunctions: {} })
+    return { fxns: this.#fxns, vars: this.#vars }
+  }
+
+  _initVariables (playbook) {
+    return (this.#vars = Object.setPrototypeOf(
+      { playbook },
+      {
+        lock (name) {
+          return Object.defineProperty(this, name, { configurable: false, writable: false })[name]
+        },
+        remove (name) {
+          const currentValue = this[name]
+          delete this[name]
+          return currentValue
+        },
+      }
+    ))
+  }
+
+  _registerExtensions (playbook, vars) {
+    const extensions = (playbook.antora || {}).extensions || []
+    if (extensions.length) {
+      const requireContext = { dot: playbook.dir, paths: [playbook.dir || '', this.module.path] }
+      extensions.forEach((ext) => {
+        const { enabled = true, id, require: request, ...config } = ext.constructor === String ? { require: ext } : ext
+        if (!enabled) return
+        const { register } = userRequire(request, requireContext)
+        if (typeof register !== 'function') return
+        if (register.length) {
+          if (FUNCTION_WITH_POSITIONAL_PARAMETER_RX.test(register.toString().replace(NEWLINES_RX, ' '))) {
+            register.length === 1 ? register(this) : register(this, Object.assign({ config }, vars))
+          } else {
+            register.call(this, Object.assign({ config }, vars))
+          }
+        } else {
+          register.call(this)
+        }
+      })
+    }
+    if (this.eventNames().length) return
+    const notify = async () => undefined
+    Object.defineProperty(this, 'notify', { value: notify })
+  }
+
+  _registerFunctions () {
+    this.#fxns = Object.entries(
+      Object.entries(FUNCTION_PROVIDERS).reduce((accum, [fxnName, moduleKey]) => {
+        accum[moduleKey] = (accum[moduleKey] || []).concat(fxnName)
+        return accum
+      }, {})
+    ).reduce((accum, [moduleKey, fxnNames]) => {
+      const defaultExport = this.require('@antora/' + moduleKey)
+      const defaultExportName = defaultExport.name
+      fxnNames.forEach((fxnName) => {
+        const fxn = fxnName === defaultExportName ? defaultExport : defaultExport[fxnName]
+        accum[fxnName] = fxn.bind(this)
+      })
+      return accum
+    }, {})
+  }
+}
+
+module.exports = GeneratorContext

package/lib/index.js

@@ -3,10 +3,9 @@
 /**
  * Default Site Generator component for Antora
  *
- * Runs an Antora pipeline using the default set of components with a focus on
- * producing and publishing a documentation site. This component represents
- * just one way the Antora components can be organized into a site generation
- * pipeline.
+ * Coordinates a default set of software components to produce and publish a
+ * documentation site. This component represents just one way the Antora
+ * components can be organized to make a documentation generator.
  *
  * @namespace site-generator-default
  */

package/lib/site-catalog.js

@@ -0,0 +1,28 @@
+'use strict'
+
+const $files = Symbol('files')
+
+class SiteCatalog {
+  constructor () {
+    this[$files] = []
+  }
+
+  addFile (file) {
+    this[$files].push(file)
+  }
+
+  addFiles (files) {
+    this[$files].push(...files)
+  }
+
+  getFiles () {
+    return this[$files].slice()
+  }
+}
+
+/**
+ * @deprecated superceded by getFiles(); scheduled to be removed in Antora 4
+ */
+SiteCatalog.prototype.getAll = SiteCatalog.prototype.getFiles
+
+module.exports = SiteCatalog

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@antora/site-generator-default",
-  "version": "3.0.0-alpha.7",
-  "description": "The default site generator pipeline for producing and publishing static documentation sites with Antora.",
+  "version": "3.0.0-beta.2",
+  "description": "The default site generator for producing and publishing static documentation sites with Antora.",
   "license": "MPL-2.0",
   "author": "OpenDevise Inc. (https://opendevise.com)",
   "contributors": [
@@ -15,20 +15,24 @@
   },
   "main": "lib/index.js",
   "dependencies": {
-    "@antora/asciidoc-loader": "3.0.0-alpha.7",
-    "@antora/content-aggregator": "3.0.0-alpha.7",
-    "@antora/content-classifier": "3.0.0-alpha.7",
-    "@antora/document-converter": "3.0.0-alpha.7",
-    "@antora/navigation-builder": "3.0.0-alpha.7",
-    "@antora/page-composer": "3.0.0-alpha.7",
-    "@antora/playbook-builder": "3.0.0-alpha.7",
-    "@antora/redirect-producer": "3.0.0-alpha.7",
-    "@antora/site-mapper": "3.0.0-alpha.7",
-    "@antora/site-publisher": "3.0.0-alpha.7",
-    "@antora/ui-loader": "3.0.0-alpha.7"
+    "@antora/asciidoc-loader": "3.0.0-beta.2",
+    "@antora/content-aggregator": "3.0.0-beta.2",
+    "@antora/content-classifier": "3.0.0-beta.2",
+    "@antora/document-converter": "3.0.0-beta.2",
+    "@antora/logger": "3.0.0-beta.2",
+    "@antora/navigation-builder": "3.0.0-beta.2",
+    "@antora/page-composer": "3.0.0-beta.2",
+    "@antora/redirect-producer": "3.0.0-beta.2",
+    "@antora/site-mapper": "3.0.0-beta.2",
+    "@antora/site-publisher": "3.0.0-beta.2",
+    "@antora/ui-loader": "3.0.0-beta.2",
+    "@antora/user-require-helper": "~2.0"
+  },
+  "devDependencies": {
+    "@antora/playbook-builder": "3.0.0-beta.2"
   },
   "engines": {
-    "node": ">=10.17.0"
+    "node": ">=12.21.0"
   },
   "files": [
     "lib/"
@@ -42,5 +46,5 @@
     "static site",
     "web publishing"
   ],
-  "gitHead": "fbd597b3680474f2083cda8a7facf1e2848c08e0"
+  "gitHead": "5cd3f9cc70622e465cb44daf1aa2035ed5a35f54"
 }