Collector Use Cases

This page presents realistic use cases that can be accomplished using Collector. Each section introduces a different use case and presents the configuration and commands you can use as a starting point.

Import example code

You can use Collector to import files that are stored outside the content source root so they can be included in pages in the site.

Let’s assume that the branch of our content repository has the following structure:

pom.xml
docs/
  antora.yml
  modules/
    ROOT/
      pages/
        index.adoc
src/
  test/
    java/
      org/
        example/
          HelloWorld.java

To include the file HelloWorld.java into the page index.adoc, you’re instinct may be to use a relative path reference.

include::../../../../src/test/java/org/example/HelloWorld.java[]

However, Antora does not permit references to files that are stored outside of a content source root (as these files are outside of Antora’s virtual file system). Instead, we can use Collector to import those files into Antora’s content catalog so they can be referenced.

Here’s the configuration to add to antora.yml to set this up:

ext:
  collector:
    scan:
      dir: src/test/java
      into: modules/ROOT/examples

This configuration imports all the files under src/test/java into the modules/ROOT/examples virtual path in the component version bucket. (You can use the files key to filter the files that are matched). The result is that these files will be classified into the example family of the ROOT module.

Now you can include the HelloWorld.java file as follows:

include::example$org/example/HelloWorld.java[]

Collector has effectively copied the files from src/test/java into docs/modules/ROOT/examples at runtime without having to physically copy them.

Generate API docs as attachments

You may want to embed API docs into your Antora-generated site. The challenge is that since API docs are generated from the code, you don’t want to have to commit these files to repository. Collector can offer to generate the files from the code that’s in the same branch as the content while Antora is running and import them as attachments. This works even when the content repository is remote since Collector has the ability to checkout each git reference into a worktree if necessary.

Let’s assume that the branch of our content source repository has the following structure:

pom.xml
docs/
  antora.yml
  modules/
    ROOT/
      pages/
        index.adoc
src/
  main/
    java/
      com/
        acme/
          Application.java

We’ll also assume that we can build the API docs (in this case Javadoc) using the command mvn javadoc:javadoc.

Here’s the configuration to add to antora.yml to set this up:

ext:
  collector:
    run: mvn javadoc:javadoc
    scan:
      clean: true (1)
      dir: target/apidocs
      into: modules/api/attachments

1	Instructs Collector to clean the scan directory before running the command.

This Collector instance first runs the mvn javadoc:javadoc command (making the assumption that the mvn command is available on the current user’s PATH). It that scans for and imports all the files under the generated target/apidocs directory into the modules/api/attachments virtual path in the component version bucket. The result is that these files will be classified into the attachment family of the api module.

We can now link the reader to the API docs using the following xref:

Consult the xref:api:attachment$index.html[API].

This workflow can be done for all sorts of API docs.

Replace version with value from build

The documentation version (i.e., the component version) is typically stored in the component version descriptor (antora.yml) or derived from the git reference. A common need is to pick up the version from the project’s build. Replacing the documentation version with the value from the build can be orchestrated using Collector.

We’ll want to start by binding the documentation version to the git reference. This ensures that the version is still unique when Collector is not enabled. To do so, we’ll set the version to the value of true in the component descriptor.

docs/antora.yml

name: my-project
version: true
title: My Project
nav:
- modules/ROOT/nav.adoc

Next, we’ll want to add a task to the build that passes on the project version from the build to Antora. This hand-off is done by having the build generate an antora.yml to update the value of the version key.

Let’s assume that we’re using a Gradle build. First, we’ll define the project version in the gradle.properties file, where the version will be managed.

gradle.properties

version: 1.0.1

Next, let’s add a new task in build.gradle that generates the antora.yml file. It’s only necessary to include the keys you want updated, in this case version.

build.gradle

// ...

tasks.register('generateAntoraYml') {
  group = 'Documentation'
  description = 'Generates antora.yml to populate version and AsciiDoc attributes'
  doLast {
    def toFile = new File("$buildDir/generated-docs/antora.yml")
    toFile.getParentFile().mkdirs()
    toFile.createNewFile()
    toFile.setText("version: '${project.version}'\n")
  }
}

This task could abbreviate the project version to the major.minor form (e.g., 1.0), as is customary for documentation sites.

Now we need to configure Collector to run the generateAntoraYml task and scan for the result. We’ll configure the project with the Gradle wrapper so Gradle can be run from the worktree (i.e., locally) using gradlew (which will be translated by Collector to gradlew.bat on Windows).

docs/antora.yml

name: my-project
version: true
# ...
ext:
  collector:
    run:
      command: gradlew -q generateAntoraYml
      local: true
    scan: build/generated-docs

This content source is now ready to be used in an Antora site. By the time Antora classifies the component version, the version value will be 1.0.1 rather than the name of the git reference.