Class TopicRegistryMojo

java.lang.Object
network.ike.docs.plugin.TopicRegistryMojo
All Implemented Interfaces:
org.apache.maven.api.plugin.Mojo

@Mojo(name="topic-registry", defaultPhase="validate") public class TopicRegistryMojo extends Object implements org.apache.maven.api.plugin.Mojo
Generate the topic registry: every AsciiDoc file under the module's source root, with its storage location and header metadata (the :topic-*: block of a topic fragment; the title, document attributes and include count of any file), written to target/topic-registry.yaml in the shape IKE-TOPIC-REGISTRY.md gives the registry: topics grouped into domains by the prefix of their id. The same structure is printed to the build log as a tree. It applies to every module the doc pipeline renders: topic libraries, assemblies, doc-only and hybrid projects.

This is the topic registry's build-time revision: the registry keeps its purpose and shape and is now generated from the files on every run instead of kept by hand at src/docs/asciidoc/topic-registry.yaml. It is never committed and never edits a source file. Header findings (a missing required attribute, an anchor that does not match the id, an unknown type or status, the same id in two files) are reported in the registry and the log and do not fail the build.

A module without src/docs/asciidoc is skipped with one log line, so the goal can run from a reactor root. Usage:

  mvn idoc:topic-registry                                          # the module's src/docs/asciidoc
  mvn idoc:topic-registry -Dike.topic-registry.roots=a,b           # other roots, comma-separated
  mvn idoc:topic-registry -Dike.topic-registry.output=/tmp/r.yaml  # write elsewhere
  mvn idoc:topic-registry -Dike.topic-registry.add=topics/x/new.adoc   # add one ingested file, no rescan
  mvn idoc:topic-registry -Dike.topic-registry.rootFile=src/docs/asciidoc/index.adoc  # only what index.adoc includes

With -Dike.topic-registry.rootFile the registry holds that file and the .adoc files it reaches through include:: lines, recursively; other files under the root are left out. The file must lie under one of the roots, and paths stay relative to that root. Includes that cannot be followed (an attribute reference such as {topicsdir}/, an absolute path, a URI, a missing file) are findings. It cannot be combined with add.

With -Dike.topic-registry.add the named files are parsed alone and merged into the existing registry: placed in their domain, counted, and checked for a duplicate id against the registry. An entry for the same file is replaced, so re-ingesting is safe. Deleted files are not noticed that way; a run without add re-derives everything.

The default phase is validate: the goal reads sources and writes only under target/, so an execution declared without a phase (as ike-parent does for lint-site) refreshes the registry on every build, including a bare mvn validate.

With the POM property ike.adoc.layout=packages (dev-adoc-packages, IKE-Network/ike-issues#1341) the registry is blob-keyed and incremental: GitBlobIndex lists every file with the git blob id of its content without opening it, and IncrementalRegistry keeps the entry of a file whose path and blob are unchanged, re-keys the entry of a blob that moved, parses only a new or changed blob and drops a path that is gone. A tree without git falls back to hashing every file in Java, the full scan's cost. The registry and the term index are then written to target/adoc-meta/META-INF/ike/<groupId>/<artifactId>/topic-registry.yaml and term-index.yaml, which the parent POM ships in the adoc zip, with every file: relative to the AsciiDoc root; add is a special case of the blob rule and needs no separate path. Without the property nothing above changes.

Skip with -Dike.skip.topic-registry=true.

Since:
109
  • Constructor Details

    • TopicRegistryMojo

      public TopicRegistryMojo()
      Creates this goal instance.
  • Method Details

    • getLog

      protected org.apache.maven.api.plugin.Log getLog()
      Access the Maven logger.
      Returns:
      the logger
    • execute

      public void execute() throws org.apache.maven.api.plugin.MojoException
      Specified by:
      execute in interface org.apache.maven.api.plugin.Mojo
      Throws:
      org.apache.maven.api.plugin.MojoException