[go: up one dir, main page]

Add support for specifying bucket key on scan action

Currently, Collector assumes that all scan files should be imported into the current bucket from which collector is run (the name and version from antora.yml that contains ext.collector). Some users may want to run collector from one bucket then have it import files into a different bucket. One such example is a command that creates API docs. Instead of storing the generated API docs in the bucket for the origin from which they were created, the user may want to have those files contributed to dedicated component, such as a versionless component named apidocs.

Add support for the bucket key on the scan action. This key will specify a component version using the resource reference syntax. Both the component name and version are required since, at this point in the generation, there's no concept of a latest version (e.g., 3.1@acme or @apidocs).

ext:
  collector:
    scan:
      dir: .
      bucket: '@apidocs'

If there's no bucket for this component version, it should be created automatically and associated with the current origin (which will happen automatically by just adding a new bucket in the aggregate).

Alternately, the user should be able to specify the component version in a scanned antora.yml file. If the value of the name key is different than the component name for the current bucket, Antora should assume it's a reference to a different bucket (rather than trying to change the name of the current component version).

The trickier part is what to do with the value of the version key in the imported antora.yml. Currently, if it's different, Antora updates the version on the current bucket. This is done to allow collector to refine the version of the component. I think this behavior needs to be retained.

However, this is ambiguous if collector is also allowed to contribute files to a different component version. We may need a hint somewhere that communicates how to interpret a version value that is different from the value on the current bucket.

One idea is to allow the bucket key to be set to null.

ext:
  collector:
    scan:
      dir: .
      bucket: ~

This indicates that the linkage to the current bucket should be severed and that the files should be put in the bucket specified in antora.yml as is. In this case, no updates to the existing bucket's metadata are made (unless an exact match is made to a component version).

Edited by Dan Allen