Class DocDiffMojo

java.lang.Object
network.ike.docs.plugin.DocDiffMojo
All Implemented Interfaces:
org.apache.maven.api.plugin.Mojo
@Mojo(name="diff") public class DocDiffMojo extends Object implements org.apache.maven.api.plugin.Mojo
Generate and render a doc-diff review packet: every changed AsciiDoc fragment between two refs (or a ref and the working tree), marked inline with [.diff-ins]/[.diff-del] roles and composed into a book with a cover summary, Record of Changes, Change Glossary, Change Index, registry delta, and assembly scaffolding diffs (ike-issues#648, #649, #650; design note dev-doc-diff-pipeline in ike-lab-documents).

The goal works at the Maven subproject level and adapts to the module it runs in:

  • Topics-library module (its source root holds topic-registry.yaml): the corpus packet — every changed fragment, the full registry delta including each assembly's membership changes, and the module's own scaffolding.
  • Assembly module: the packet is the projection of the corpus diff onto this assembly — changed topics intersected with the assembly's flattened topic-refs (assembly id defaults to the artifactId; topic ids resolve to files through the per-domain registries), plus the module's own master-file scaffolding diff and a membership delta for just this assembly. Topics deleted in range are reported by the membership delta rather than projected.
  • Other modules: no source directory → skipped silently; no changes → skipped with a note. Invoking the goal from the aggregator therefore produces a packet for every subproject able to generate one.

Typical invocations: 

  mvn idoc:diff                                  # HEAD vs working tree
  mvn idoc:diff -Dike.diff.from=v1.2.3           # tag vs working tree
  mvn idoc:diff -Dike.diff.from=A -Dike.diff.to=B  # any two commits

Change entities come from changes.yaml — looked up first beside the module pom, then at the repository work-tree root. For commit-to-commit comparisons without one, they are derived by grouping the range's commits on their Refs:/Fixes: trailers (ike-issues#652); a working-tree comparison without one gets a single synthetic "uncommitted changes" entity.

Both sides' content always renders through the current toolchain — the diff is of knowledge, never of the renderer. Deleted fragments are listed on the cover and in the registry delta rather than rendered struck-through (v1 decision per #649). Diagram blocks inside marked topics render as source listings in this goal's output; full diagram fidelity comes from the regular pipeline render of a packet wired as a doc module.

Outputs under target/doc-diff/: asciidoc/ (the generated packet sources), html/, and pdf/ (prawn). Skip rendering with -Dike.diff.render=false.

See Also:

  • Constructor Details

    • DocDiffMojo

      public DocDiffMojo()

  • 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