Class TopicRegistryMojo
- All Implemented Interfaces:
org.apache.maven.api.plugin.Mojo
: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 Summary
Constructors -
Method Summary
-
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:
executein interfaceorg.apache.maven.api.plugin.Mojo- Throws:
org.apache.maven.api.plugin.MojoException
-