Support Antora Collector in the IDE

[ahus1]

Why the new feature should be added

When creating content with Antora Collector, this content is not yet found by the AsciiDoc plugin, thereby leaving broken images in the preview, or missing includes.

How the new feature should work

The content as configured in the "scan" elements of the Antora component descriptor for the collector extension should resolved as described in the "base" and "dir" attributes, and eventually also the "files" attribute.

See the Eclipse Che Docs for an example.

The current state is described in the docs: https://intellij-asciidoc-plugin.ahus1.de/docs/users-guide/features/advanced/antora.html#antora-collector-extension-support

[mojavelinux]

This reminds me of an annotation processor in Java. We might want to consider having the plugin run the command to generate the files if they aren't already there. An up-to-date check would be tricky, so perhaps some sort of manual run task would be needed, possibly one set up by the writer.

[mojavelinux]

Take note of the following open issue: https://gitlab.com/antora/antora-collector-extension/-/issues/4

[ahus1]

Started to work on this as I might need it myself early next year.

The support for filtering with the file attribute won't work in the first version as I didn't find a globing library for Java yet that matches the functionality that is available in Node out-of-the-box. Any hint for a library would be great.

Will use the Eclipse Che docs as an example as linked above.

If someone wants to collaborate, please let me know of other projects which use it which could serve for trial runs.

[mojavelinux]

If someone wants to collaborate, please let me know of other projects which use it which could serve for trial runs.

I think Spring Security could be a good test. See https://github.com/spring-projects/spring-security/blob/main/docs/antora.yml It has a unique requirement that the JVM must be set up in the shell that collector uses in order for the task to succeed.

I didn't find a globing library for Java yet that matches the functionality that is available in Node out-of-the-box.

Node.js doesn't have globbing out of the box either. We're using glob-stream, which is a third-party library. See https://gitlab.com/antora/antora-collector-extension/-/blob/main/packages/collector-extension/lib/index.js#L10

[ahus1]

It has a unique requirement that the JVM must be set up in the shell that collector uses in order for the task to succeed.

The first implementation will focus on getting "scan" sufficiently right to help a technical writer to reference the content collected in manually written content with auto-complete, and to make validations about missing resources work. After that, I'll focus on "run".

[ahus1]

The pre-release 0.38.6 contains the first support for Antora collector // cc: @themr0c

It supports the properties scan.dir, scan.base, and it allows to overwrite Antora resources like pages and the properties of an Antora component descriptor. I've tested it with the Eclipse Che and the Spring Security docs.

[ahus1]

There is at least this port of "minimatch" which would allow for implementing globbing for the scan.file attribute: https://github.com/jshaptic/minimatch-javaport

[ahus1]

The plugin docs have been updated to state that the the plugin supports the scan.dir option only for paths relative to the component descriptor. Those relative paths start with a ./. While this makes it simpler for the plugin, this isn't documented on the Antora Collector's homepage.

More work is necessary on the plugin's side to support also absolute paths from the content root.

[mojavelinux]

this isn't documented on the Antora Collector's homepage.

The docs are being migrated (gradually) to the docs folder. Here's the current list of keys and their meanings: https://gitlab.com/antora/antora-collector-extension/-/blob/main/docs/modules/ROOT/pages/configuration-keys.adoc?ref_type=heads#collector-reference