@antora/site-generator-default 3.0.0-alpha.6 → 3.0.0-beta.1

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,32 +1,62 @@
 '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])
+async function generateSite (playbook) {
+  try {
+    const context = new GeneratorContext(playbook, module)
+    const { fxns, vars } = context
+    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')
+    }
+    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.isHaltSignal(err)) throw err
+  }
 }
 
 function create404Page () {

package/lib/generator-context.js

@@ -0,0 +1,160 @@
+'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',
+}
+
+class HaltSignal extends Error {}
+
+class GeneratorContext extends EventEmitter {
+  #fxns
+  #vars
+
+  constructor (playbook, module_) {
+    super()
+    if (!('path' in (this.module = module_))) module_.path = require('path').dirname(module_.filename)
+    this._registerFunctions(module_)
+    this._registerExtensions(playbook, this._initVariables(playbook), module_)
+    Object.defineProperties(this, { _initVariables: {}, _registerExtensions: {}, _registerFunctions: {} })
+  }
+
+  getFunctions () {
+    return arguments.length ? this.#fxns : Object.assign({}, this.#fxns)
+  }
+
+  getLogger (name = 'antora') {
+    return getLogger(name)
+  }
+
+  getVariables () {
+    return Object.assign({}, this.#vars)
+  }
+
+  halt () {
+    throw new HaltSignal()
+  }
+
+  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).map(([name, fxn]) => {
+      if (name in fxns) fxns[name] = fxn.bind(this)
+    })
+  }
+
+  require (request) {
+    return this.module.require(request)
+  }
+
+  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
+    }
+  }
+
+  // TODO remove updateVars before Antora 3.0.0
+  updateVars (updates) {
+    return this.updateVariables(updates)
+  }
+
+  static isHaltSignal (err) {
+    return err instanceof HaltSignal
+  }
+
+  _initVariables (playbook) {
+    Object.defineProperty(this, 'vars', {
+      configurable: true,
+      get: () => {
+        delete this.vars
+        return Object.setPrototypeOf(this.#vars, {
+          lock (name) {
+            return Object.defineProperty(this, name, { configurable: false, writable: false })[name]
+          },
+          remove (name) {
+            const currentValue = this[name]
+            delete this[name]
+            return currentValue
+          },
+        })
+      },
+    })
+    return (this.#vars = { playbook })
+  }
+
+  _registerExtensions (playbook, vars, module_) {
+    const extensions = (playbook.antora || {}).extensions || []
+    if (extensions.length) {
+      const requireContext = { dot: playbook.dir, paths: [playbook.dir || '', 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 *)?(?:\w+ *)?\( *\w|^\w+(?: *, *\w+)* *=>/.test(register.toString().replace(/\r?\n/g, ' '))) {
+            register.length === 1 ? register(this) : register(this, Object.assign({ config }, vars))
+          } else {
+            register.call(this, Object.assign({ config }, vars))
+          }
+        } else {
+          register.call(this)
+        }
+      })
+    }
+    this.notify = this.eventNames().length ? this.notify.bind(this) : async () => undefined
+  }
+
+  _registerFunctions (module_) {
+    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 = module_.require('@antora/' + moduleKey)
+      const defaultExportName = defaultExport.name
+      fxnNames.forEach((fxnName) => {
+        const fxn = fxnName === defaultExportName ? defaultExport : defaultExport[fxnName]
+        accum[fxnName] = fxn.bind(this)
+      })
+      return accum
+    }, {})
+    Object.defineProperty(this, 'fxns', {
+      configurable: true,
+      get: () => {
+        delete this.fxns
+        return this.#fxns
+      },
+    })
+  }
+}
+
+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.6",
-  "description": "The default site generator pipeline for producing and publishing static documentation sites with Antora.",
+  "version": "3.0.0-beta.1",
+  "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.6",
-    "@antora/content-aggregator": "3.0.0-alpha.6",
-    "@antora/content-classifier": "3.0.0-alpha.6",
-    "@antora/document-converter": "3.0.0-alpha.6",
-    "@antora/navigation-builder": "3.0.0-alpha.6",
-    "@antora/page-composer": "3.0.0-alpha.6",
-    "@antora/playbook-builder": "3.0.0-alpha.6",
-    "@antora/redirect-producer": "3.0.0-alpha.6",
-    "@antora/site-mapper": "3.0.0-alpha.6",
-    "@antora/site-publisher": "3.0.0-alpha.6",
-    "@antora/ui-loader": "3.0.0-alpha.6"
+    "@antora/asciidoc-loader": "3.0.0-beta.1",
+    "@antora/content-aggregator": "3.0.0-beta.1",
+    "@antora/content-classifier": "3.0.0-beta.1",
+    "@antora/document-converter": "3.0.0-beta.1",
+    "@antora/logger": "3.0.0-beta.1",
+    "@antora/navigation-builder": "3.0.0-beta.1",
+    "@antora/page-composer": "3.0.0-beta.1",
+    "@antora/redirect-producer": "3.0.0-beta.1",
+    "@antora/site-mapper": "3.0.0-beta.1",
+    "@antora/site-publisher": "3.0.0-beta.1",
+    "@antora/ui-loader": "3.0.0-beta.1",
+    "@antora/user-require-helper": "~2.0"
+  },
+  "devDependencies": {
+    "@antora/playbook-builder": "3.0.0-beta.1"
   },
   "engines": {
-    "node": ">=10.17.0"
+    "node": ">=12.21.0"
   },
   "files": [
     "lib/"
@@ -42,5 +46,5 @@
     "static site",
     "web publishing"
   ],
-  "gitHead": "38ec002e88eede3ce5c401a6e226d1a0356945c5"
+  "gitHead": "7c5ef1ea93dd489af533c80a936c736013c41769"
 }