@antora/site-publisher 3.0.0-beta.3 → 3.0.0-rc.1

package/README.md

@@ -1,9 +1,12 @@
 # Antora Site Publisher
 
-The Site Publisher is a component in Antora responsible for publishing (i.e., writing) the generated files to the destination(s) specified in the playbook.
-More than one destination may be specified, and this component supports different destination types (via providers) such as a filesystem directory or an archive file.
+The Site Publisher is a component in Antora responsible for publishing (i.e., writing) files in the virtual file catalog(s) to the destination(s) specified in the playbook.
+This component supports different destination types (via providers) such as a filesystem directory or an archive file.
+More than one destination may be specified.
 Custom providers can be used to add support for additional destinations.
 
+*This package is an alias for the `@antora/file-publisher` package.*
+
 [Antora](https://antora.org) is a modular static site generator designed for creating documentation sites from AsciiDoc documents.
 Its site generator aggregates documents from versioned content repositories and processes them using [Asciidoctor](https://asciidoctor.org).
 

package/lib/index.js

@@ -1,11 +1,8 @@
 'use strict'
 
 /**
- * Site Publisher component for Antora
- *
- * Publishes the files generated by the Antora generator to the destination(s)
- * specified in the playbook.
+ * An alias for the @antora/file-publisher package.
  *
  * @namespace site-publisher
  */
-module.exports = require('./publish-site')
+module.exports = require('@antora/file-publisher')

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@antora/site-publisher",
-  "version": "3.0.0-beta.3",
-  "description": "Publishes the files generated in an Antora documentation pipeline to the destination(s) specified in the playbook.",
+  "version": "3.0.0-rc.1",
+  "description": "An alias for the @antora/file-publisher package.",
   "license": "MPL-2.0",
   "author": "OpenDevise Inc. (https://opendevise.com)",
   "contributors": [
@@ -14,12 +14,11 @@
     "url": "https://gitlab.com/antora/antora/issues"
   },
   "main": "lib/index.js",
+  "scripts": {
+    "test": "_mocha"
+  },
   "dependencies": {
-    "@antora/expand-path-helper": "~2.0",
-    "@antora/user-require-helper": "~2.0",
-    "gulp-vinyl-zip": "~2.5",
-    "vinyl": "~2.2",
-    "vinyl-fs": "~3.0"
+    "@antora/file-publisher": "3.0.0-rc.1"
   },
   "engines": {
     "node": ">=12.21.0"
@@ -31,9 +30,10 @@
     "antora",
     "antora-component",
     "publisher",
+    "files",
     "documentation",
     "static site",
     "web publishing"
   ],
-  "gitHead": "45da95a2e2dea538379d2d9f42013d2208fb86c3"
+  "gitHead": "044371a33e2c0fed9724d30945bbb549d64845d5"
 }

package/lib/constants.js

@@ -1,6 +0,0 @@
-'use strict'
-
-module.exports = Object.freeze({
-  DEFAULT_DEST_FS: './build/site',
-  DEFAULT_DEST_ARCHIVE: './build/site.zip',
-})

package/lib/providers/archive.js

@@ -1,17 +0,0 @@
-'use strict'
-
-const expandPath = require('@antora/expand-path-helper')
-const publishStream = require('./common/publish-stream')
-const { dest: vzipDest } = require('gulp-vinyl-zip')
-
-const { DEFAULT_DEST_ARCHIVE } = require('../constants.js')
-
-// FIXME right now we're assuming the archive is a zip
-function publishToArchive (config, files, playbook) {
-  const destFile = config.path || DEFAULT_DEST_ARCHIVE
-  const absDestFile = expandPath(destFile, { dot: playbook.dir })
-  const report = { provider: 'archive', path: destFile, resolvedPath: absDestFile }
-  return publishStream(vzipDest(absDestFile), files).then(() => report)
-}
-
-module.exports = publishToArchive

package/lib/providers/common/publish-stream.js

@@ -1,26 +0,0 @@
-'use strict'
-
-/**
- * Pipes the stream of files to the specified Vinyl destination adapter.
- *
- * Pipes a stream of virtual files to the specified Vinyl destination adapter
- * (a stream transform function) and returns a Promise that resolves when the
- * stream ends.
- *
- * @memberof site-publisher
- *
- * @param {Function} destAdapter - A Vinyl destination adapter, preconfigured to
- *   write to a destination (e.g., `require('vinyl-fs').dest('path/to/dir')`).
- * @param {Readable<File>} files - A Readable stream of virtual files to publish.
- * @returns {Promise} A promise that resolves when the stream has ended.
- */
-function publishStream (destAdapter, files) {
-  return new Promise((resolve, reject) =>
-    files
-      .pipe(destAdapter)
-      .on('error', reject)
-      .on('end', resolve)
-  )
-}
-
-module.exports = publishStream

package/lib/providers/fs.js

@@ -1,28 +0,0 @@
-'use strict'
-
-const expandPath = require('@antora/expand-path-helper')
-const { promises: fsp } = require('fs')
-const ospath = require('path')
-const posixify = ospath.sep === '\\' ? (p) => p.replace(/\\/g, '/') : undefined
-const publishStream = require('./common/publish-stream')
-const { dest: vfsDest } = require('vinyl-fs')
-
-const { DEFAULT_DEST_FS } = require('../constants.js')
-
-function publishToFs (config, files, playbook) {
-  const destDir = config.path || DEFAULT_DEST_FS
-  const absDestDir = expandPath(destDir, { dot: playbook.dir })
-  const report = {
-    provider: 'fs',
-    path: destDir,
-    resolvedPath: absDestDir,
-    fileUri: 'file://' + (posixify ? '/' + posixify(absDestDir) : absDestDir),
-  }
-  return config.clean
-    ? fsp['rm' in fsp ? 'rm' : 'rmdir'](absDestDir, { recursive: true, force: true })
-      .then(() => publishStream(vfsDest(absDestDir), files))
-      .then(() => report)
-    : publishStream(vfsDest(absDestDir), files).then(() => report)
-}
-
-module.exports = publishToFs

package/lib/publish-site.js

@@ -1,102 +0,0 @@
-'use strict'
-
-const ReadableOutputFileArray = require('./readable-output-file-array')
-const userRequire = require('@antora/user-require-helper')
-
-const { DEFAULT_DEST_FS } = require('./constants.js')
-
-/**
- * Publishes all publishable files in the specified catalogs using the
- * destination providers specified in the playbook.
- *
- * This function starts by retrieving all publishable files from the specified
- * collection of catalogs (currently those files with an out property). It then
- * resolves the publish function for each destination provider specified in the
- * playbook (i.e., `output.destinations`). If the provider is not known, the
- * publish function for that provider is resolved by requiring a module (or
- * relative path) having the same name as the provider.  Once the publish
- * function is resolved, the configuration specified in the playbook for that
- * provider is bound to the function as its first argument.  This function then
- * iterates over all publish providers and passes a Readable of the publishable
- * files as the second argument and the playbook as the third. The path of each
- * file has been updated to match the `out.path` value (currently by
- * instantiating a copy of the file).
- *
- * If a directory is specified directly on the output property of the playbook
- * (i.e., `output.dir`), that directory is used to create or override the first
- * fs provider in the list of destinations. If the clean property is set directly
- * on the output property of the playbook (i.e., `output.clean`), the clean
- * property is added to the configuration for each provider.
- *
- * @memberof site-publisher
- *
- * @param {Object} playbook - The configuration object for Antora that provides
- *   access to the output destinations.
- * @param {Array<Catalog>} catalogs - The collection of catalogs from which to retrieve the
- *   publishable virtual files.
- * @returns Nothing.
- */
-// QUESTION should this function return a report of virtual files that were published (by provider)
-async function publishSite (playbook, catalogs) {
-  const output = playbook.output
-  const destinations = getDestinations(output)
-
-  if (!destinations.length) return []
-
-  const clean = output.clean
-  const publishers = destinations.map((destination) => {
-    const { provider, options } = resolveDestination(destination, clean)
-    switch (provider) {
-      case 'archive':
-      case 'fs':
-        return require('./providers/' + provider).bind(null, options)
-      default:
-        try {
-          const userRequireContext = { dot: playbook.dir, paths: [playbook.dir || '', __dirname] }
-          return userRequire(provider, userRequireContext).bind(null, options)
-        } catch (err) {
-          const prettyErr = new Error('Unsupported destination provider: ' + provider)
-          prettyErr.stack += `\nCaused by: ${err.stack || err}`
-          throw prettyErr
-        }
-    }
-  })
-
-  // Q: add getPublishableFiles / getOutFiles; return a stream? or getOutFilesAsStream?
-  const filesToPublish = catalogs.reduce((accum, catalog) => {
-    // remove fallback check for getFiles on site catalog in Antora 4
-    accum.push(...(catalog.getFiles || catalog.getAll).apply(catalog).filter((file) => file.out))
-    return accum
-  }, [])
-
-  return Promise.all(publishers.map((publish) => publish(new ReadableOutputFileArray(filesToPublish), playbook)))
-}
-
-function getDestinations (output) {
-  let destinations = output.destinations
-  if (output.dir) {
-    if (destinations && destinations.length) {
-      destinations = destinations.slice()
-      const primaryFsDestIdx = destinations.findIndex(({ provider: candidate }) => candidate === 'fs')
-      if (~primaryFsDestIdx) {
-        ;(destinations[primaryFsDestIdx] = Object.assign({}, destinations[primaryFsDestIdx])).path = output.dir
-      } else {
-        destinations.unshift({ provider: 'fs', path: output.dir })
-      }
-    } else {
-      destinations = [{ provider: 'fs', path: output.dir }]
-    }
-  } else if (!destinations) {
-    destinations = [{ provider: 'fs', path: DEFAULT_DEST_FS }]
-  }
-
-  return destinations
-}
-
-function resolveDestination (destination, clean) {
-  const { provider, ...options } = destination
-  if (clean) options.clean = true
-  return { provider, options }
-}
-
-module.exports = publishSite

package/lib/readable-output-file-array.js

@@ -1,34 +0,0 @@
-'use strict'
-
-const { Readable } = require('stream')
-const Vinyl = require('vinyl')
-
-class File extends Vinyl {
-  get relative () {
-    return this.path
-  }
-}
-
-class ReadableOutputFileArray extends Readable {
-  constructor (array) {
-    super({ objectMode: true })
-    this._array = array.slice().reverse()
-  }
-
-  _read (size) {
-    const array = this._array
-    while (size--) {
-      const next = array.pop()
-      if (next === undefined) break
-      this.push(toOutputFile(next))
-    }
-    if (size > -1) this.push(null)
-  }
-}
-
-function toOutputFile (file) {
-  // Q: do we also need to clone contents and stat?
-  return new File({ contents: file.contents, path: file.out.path, stat: file.stat })
-}
-
-module.exports = ReadableOutputFileArray