From 2d6464eb738cc54c8d4f9010899b980c78419adb Mon Sep 17 00:00:00 2001 From: Dan Allen Date: Tue, 21 May 2024 16:55:15 -0600 Subject: [PATCH] resolves #4 rename base key on scan entry to into; document key --- CHANGELOG.adoc | 1 + .../ROOT/pages/configuration-keys.adoc | 44 ++++++++++++++++--- packages/collector-extension/lib/index.js | 6 +-- .../test/collector-extension-test.js | 4 +- 4 files changed, 44 insertions(+), 11 deletions(-) diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc index df31076..5d09b4d 100644 --- a/CHANGELOG.adoc +++ b/CHANGELOG.adoc @@ -21,6 +21,7 @@ For a detailed view of what's changed, refer to the {url-repo}/commits[commit hi * upgrade isomorphic-git and make use of new force flag on branch function * automatically set release AsciiDoc attributes in docs descriptor during release (#6) +* rename `base` key on scan entry to `into` to make its purpose more clear (#4) === Fixed diff --git a/docs/modules/ROOT/pages/configuration-keys.adoc b/docs/modules/ROOT/pages/configuration-keys.adoc index 0593074..a9257c0 100644 --- a/docs/modules/ROOT/pages/configuration-keys.adoc +++ b/docs/modules/ROOT/pages/configuration-keys.adoc @@ -51,7 +51,7 @@ If the `collector` key isn't set in a component version descriptor, or its value == clean key The `clean` key must be nested under the `collector` key. -The `clean` key accepts a list of built-in key-value pairs that configure the directory (`dir`) to clean. +If the `collector` key is an array, the `clean` key must be specified as a key on one of its entries. .antora.yml [,yaml] @@ -73,7 +73,8 @@ ext: dir: artifacts ---- -The `clean` key accepts an array of items (i.e., list) that each have a `dir` key. +The `clean` key accepts an array of items (i.e., list). +An entry in the `clean` key is a map with a single key, `dir`, which specifies the directory to clean. Each `clean` entry is invoked sequentially in the order specified in the array. If there's only a single entry, the array can be replaced by a map for a single entry. @@ -115,8 +116,8 @@ Each `run` key is invoked sequentially in the order specified in the array. [#scan-key] == scan key -The `scan` key can be nested under the `collector` key if there's only a single collector entry, or in an item in the array of entries on the `collector` key. -The `scan` key accepts a list of built-in key-value pairs that configure the scan directory (`dir`) and file filter (`files`). +The `scan` key must be nested under the `collector` key. +If the `collector` key is an array, the `scan` key must be specified as a key on one of its entries. .antora.yml [,yaml] @@ -138,12 +139,32 @@ ext: dir: artifacts ---- -The `scan` key accepts an array of items (i.e., list) that have the nested keys. +The `scan` key accepts an array of items (i.e., list). +An entry in the `scan` key is a map of built-in key-value pairs that configure the scan, which includes the directory (`dir`) and file filter (`files`). Each `scan` entry is invoked sequentially in the order specified in the array. -If there's only a single entry, the array can be replaced by a map of a single entry. +If there's only a single entry, the array can be replaced by a map for a single entry. If the `clean: true` key is set on the entry, that implicitly creates a clean entry with the same dir. +For each file discovered by a scan, an virtual file entry is added to the entry in the content aggregate for the current component and version. +The file is added using the path relative to the scan dir (e.g., [.path]_modules/ROOT/pages/generated.adoc_). + +If the `into` key is specified, that value is prepended to the relative path of the file. +For example: + +[,yaml] +---- +scan: + dir: build/pages + into: modules/ROOT/pages +---- + +By using the `into` key, the scanned files do not have to be organized in the standard Antora structure. + +The files discovered by a scan operation are added to the content aggregate *before* the content is classified. +Thus, these files become indistinguishable from ones that are discovered in a content root. +It's as though the discovered files are the repository branch that Antora scans, only they are added dynamically after the fact. + [#collector-reference] == Available Collector keys @@ -193,6 +214,17 @@ Otherwise, the path is resolved relative to the worktree. The `files` key accepts a pattern (supporting the same syntax as the `worktrees` key on a content source in Antora). |All files found in the scan directory |Glob pattern + +|`scan.into` +|Specifies a path to prepend to the relative path of all files discovered by the current scan operation. +This path should also be relative (e.g., [.path]_modules/ROOT/pages_) +|Not set +|Path relative to the content root + +|`scan.clean` +|Specifies that the scanned path should be cleaned before processing this collector entry. +|Not set (false) +|Boolean |=== WARNING: This is alpha software! diff --git a/packages/collector-extension/lib/index.js b/packages/collector-extension/lib/index.js index 2db31ef..6af4fd6 100644 --- a/packages/collector-extension/lib/index.js +++ b/packages/collector-extension/lib/index.js @@ -87,7 +87,7 @@ module.exports.register = function () { } } for (const scan of scans) { - for (const file of await srcFs(scan.dir, scan.files, scan.base)) { + for (const file of await srcFs(scan.dir, scan.files, scan.into)) { let existingFile const relpath = file.path if (relpath === 'antora.yml') { @@ -167,14 +167,14 @@ function getBaseCacheDir ({ dir: dot, runtime: { cacheDir: preferredDir } }) { : expandPath(preferredDir, { dot }) } -function srcFs (cwd, globs = '**/*', base) { +function srcFs (cwd, globs = '**/*', into) { return new Promise((resolve, reject, cache = Object.create(null), accum = [], relpathStart = cwd.length + 1) => pipeline( globStream(globs, Object.assign({ cache, cwd }, GLOB_OPTS)), forEach(({ path: abspathPosix }, _, done) => { if (cache[abspathPosix].constructor === Array) return done() // detects some directories const abspath = ospath.sep === '\\' ? ospath.normalize(abspathPosix) : abspathPosix - const relpath = base ? path.join('.', base, abspath.substr(relpathStart)) : abspath.substr(relpathStart) + const relpath = into ? path.join('.', into, abspath.substr(relpathStart)) : abspath.substr(relpathStart) fsp.stat(abspath).then( (stat) => { if (stat.isDirectory()) return done() // detects directories that slipped through cache check diff --git a/packages/collector-extension/test/collector-extension-test.js b/packages/collector-extension/test/collector-extension-test.js index e442624..736c1ec 100644 --- a/packages/collector-extension/test/collector-extension-test.js +++ b/packages/collector-extension/test/collector-extension-test.js @@ -536,7 +536,7 @@ describe('collector extension', () => { it('should rebase files if base key is set on scan', async () => { const collectorConfig = { - scan: { dir: 'code', base: 'modules/extend/examples' }, + scan: { dir: 'code', into: 'modules/extend/examples' }, } await runScenario({ repoName: 'test-at-start-path', @@ -555,7 +555,7 @@ describe('collector extension', () => { it('should drop leading / on value of base key', async () => { const collectorConfig = { - scan: { dir: 'code', base: '/modules/extend/examples' }, + scan: { dir: 'code', into: '/modules/extend/examples' }, } await runScenario({ repoName: 'test-at-start-path', -- GitLab