Hop Maven PluginDocs

Menu

hop:generate-doc

Generates documentation pages for Apache Hop pipelines (.hpl) and workflows (.hwf) from the same discovery logic as the render goal (see ). For each Hop file it produces a documentation page (AsciiDoc or Markdown) with an overview, the declared parameters, the steps (transforms/actions) and the hop flow, a reference to the rendered diagram, and an optional launch script. The index page is generated from the Hop files themselves (no configuration required), with optional io.yupiik.hop.maven.documentation.Enrichment overrides for the human-written prose and ordering. When includeImage is enabled the render diagram logic is reused to also emit the image files next to the docs; when includeMd is enabled the pages are mirrored as Markdown plus an llms.txt file (see https://llmstxt.org ).

The human prose is supplied either inline through enrichments or, by convention, through a per-artefact AsciiDoc file in enrichmentLocation (src/main/hop/documentation). A documentation file keeps the narrative order of the page: its overview (the prose before the first ==), its == sections and the launch script are rendered in the order they are written, and the generated sections (configuration, steps, flow, diagram) can be placed exactly where the thread needs them with a reserved heading == :configuration, == :steps, == :flow or == :diagram. Prose that follows a heading stays under it and nested === headings are preserved. Inline enrichments (no ordered file body) keep the canonical order Overview, Configuration, Steps, Flow, Diagram, Script, then the extra sections.

Coordinates

<plugin>
  <groupId>io.yupiik.hop</groupId>
  <artifactId>hop-maven-plugin</artifactId>
  <version>1.0.1-SNAPSHOT</version>
</plugin>

To call this goal from the command line execute: mvn hop:generate-doc.

To bind this goal in the build you can use: 

<plugin>
  <groupId>io.yupiik.hop</groupId>
  <artifactId>hop-maven-plugin</artifactId>
  <version>1.0.1-SNAPSHOT</version>
  <executions>
    <execution>
      <id>my-execution</id>
      <goals>
        <goal>generate-doc</goal>
      </goals>
      <configuration>
        <!-- execution specific configuration come there -->
      </configuration>
    </execution>
  </executions>
</plugin>

You can execute this goal particularly with mvn hop:generate-doc@my-execution command.

Configuration

action2ArtifactMapping (Map)

Override mappings from action plugin id to the artifact (artifactId or full groupId:artifactId:version coordinates) shipping it. Entries take precedence over the built-in table; the default rule is org.apache.hop:hop-action-<id>.

adocHeader (String)

Extra AsciiDoc attribute lines emitted right after each page title (site breadcrumb/nav).

autoResolve (boolean)

Resolve the Hop plugin artifacts (transforms and actions) declared by the rendered diagrams with the Maven resolver, stage them and register them into the Hop registry programmatically. This removes the need to add hop-transform-* / hop-action-* modules as dependencies of this plugin for icon rendering. No JVM-global property is set; the resolution/staging phase runs outside any lock and the registration is serialized on HopEnvironment.class so several mojos can run concurrently in the same build. Default value: false. Property: ${hop.autoResolve}.

autoResolvePluginsFolder (java.io.File)

Staging folder where auto-resolved plugin jars are copied (plugin jar at the root, dependencies in a lib/ sub-folder). Only used when autoResolve is enabled. Property: ${hop.autoResolvePluginsFolder}.

autoResolveVersion (String)

Version used when a mapped artifact is given as a bare hop-transform-<id> artifactId (no explicit version). Defaults to the Hop version this plugin runs against when it can be detected, otherwise Apache Hop dependency version. Property: ${hop.autoResolveVersion}.

configCols (String)

AsciiDoc configuration table column layout. Default value: 2,2,5. Property: ${hop.doc.configCols}.

configFile (java.io.File)

JSON file declaring the Hop variables to inject before diagrams are resolved and rendered. The file may be a canonical Hop project-config.json (reading config.variables) or any JSON exposing a top-level variables array, each entry being {name, value, description}. Property: ${hop.configFile}.

configHeaders (String)

AsciiDoc configuration table header row (pipe-separated: parameter|default|description). Default value: Parameter|Default|Description. Property: ${hop.doc.configHeaders}.

configuration (boolean)

Include the configuration (parameters) section. Default value: true. Property: ${hop.doc.configuration}.

diagramReferencePrefix (String)

Prefix of the image

references in the generated AsciiDoc pages. The source-relative Hop path is appended, so the default diagrams matches the yupiik minisite layout where images live under images/diagrams. Default value: diagrams. Property: ${hop.doc.diagramReferencePrefix}.

emptyDefaultText (String)

Text shown for an empty parameter default value in the AsciiDoc configuration table. Default value: empty. Property: ${hop.doc.emptyDefaultText}.

enrichmentLocation (java.io.File)

Folder where a per-artefact documentation file (<pipelineOrWorkflowName>.adoc) is read by convention, supplying the enrichments (overview, script, index role/order, ...) for each pipeline/workflow. Falls back to inline enrichments when a file is absent. Default value: ${project.basedir}/src/main/hop/documentation. Property: ${hop.doc.enrichmentLocation}.

enrichments (List)

Manual documentation content per Hop file (overview, script, index role/order, extras...).

excludes (List)

Ant-style glob patterns excluding files from processing. Property: ${hop.excludes}.

failIfMissing (boolean)

Fail the build when a discovered pipeline/workflow has neither a documentation file in enrichmentLocation nor an inline enrichments override. Default value: true. Property: ${hop.doc.failIfMissing}.

flow (boolean)

Include the hop flow section. Default value: true. Property: ${hop.doc.flow}.

format (io.yupiik.hop.maven.mojo.GenerateDocMojo$DocFormat)

The documentation format. Each page is written with the matching renderer. Default value: ADOC. Property: ${hop.doc.format}.

generateIndex (boolean)

Whether to generate the index page listing all documented Hop files. The entries are derived from the Hop files themselves (name, kind, description); only the one-line role and the ordering can be supplied via enrichments . Default value: true. Property: ${hop.doc.generateIndex}.

imageFolder (java.io.File)

Folder where the diagram images are written when includeImage is enabled and reused by diagramReferencePrefix . Defaults to src/main/minisite/images/diagrams, the conventional yupiik minisite images location. Default value: ${project.basedir}/src/main/minisite/images/diagrams. Property: ${hop.doc.imageFolder}.

imageFormat (io.yupiik.hop.maven.render.Format)

The diagram format used when includeImage is enabled. Default value: SVG. Property: ${hop.doc.imageFormat}.

includeImage (boolean)

Whether to also render the diagram images (reusing the render goal logic) alongside the documentation. The images are written to imageFolder preserving the source relative path, and the pages reference them through diagramReferencePrefix . Default value: true. Property: ${hop.doc.includeImage}.

includeMd (boolean)

Whether to additionally emit a Markdown mirror of every page plus an llms.txt file in outputDirectory . Useful to expose LLM-friendly content (see https://llmstxt.org ), independent of the primary format . Default value: false. Property: ${hop.doc.includeMd}.

includes (List)

Ant-style glob patterns selecting files to process (applied to the source-relative path). Property: ${hop.includes}.

indexDescription (String)

Description of the generated index page. Property: ${hop.doc.indexDescription}.

indexFooter (String)

Arbitrary AsciiDoc appended at the end of the index page. Property: ${hop.doc.indexFooter}.

indexIcon (String)

Index icon used by the yupiik minisite template. Property: ${hop.doc.indexIcon}.

indexIntro (String)

Extra paragraph emitted after the index title, before the workflow/pipeline tables. Property: ${hop.doc.indexIntro}.

indexNextLabel (String)

Index page next-navigation label/link (e.g. the next sibling section). Property: ${hop.doc.indexNextLabel}.

indexNextLink (String)

Property: ${hop.doc.indexNextLink}.

indexOrder (Integer)

Ordering number of the index page in the yupiik minisite navigation. Property: ${hop.doc.indexOrder}.

indexPrevLabel (String)

Index page previous-navigation label/link (e.g. the previous sibling section). Property: ${hop.doc.indexPrevLabel}.

indexPrevLink (String)

Property: ${hop.doc.indexPrevLink}.

indexTitle (String)

Title of the generated index page. Property: ${hop.doc.indexTitle}.

llmsProjectTitle (String)

Title used in the generated llms.txt file (see includeMd ). Default value: Hop pipelines and workflows. Property: ${hop.doc.llmsProjectTitle}.

llmsSummary (String)

Summary blockquote emitted at the top of the llms.txt file. Property: ${hop.doc.llmsSummary}.

metadataFolder (java.io.File)

The metadata base folder holding the HOP metadata (rdbms, run configurations, ...). Defaults to <project.basedir>/metadata, matching the canonical Hop metadataBaseFolder={PROJECT_HOME/metadata}. Property: ${hop.metadataFolder}.

minisiteHeaders (boolean)

Emit the yupiik minisite page header attributes (index title/icon, breadcrumb, prev/next nav). Default value: true. Property: ${hop.doc.minisiteHeaders}.

outputDirectory (java.io.File)

Folder where the generated documentation is written. The index page and one page per Hop file land here (optionally preserving the source sub-folders, see preserveStructure ). Default value: ${project.basedir}/src/main/minisite/content/hop. Property: ${hop.doc.outputDirectory}.

preserveStructure (boolean)

Whether to preserve the source-relative sub-folders when writing the generated pages, or to flatten them all in outputDirectory (the workflows style). Default value: false. Property: ${hop.doc.preserveStructure}.

recursive (boolean)

Recurse into sub-folders of sourceFolder . Default value: true. Property: ${hop.recursive}.

script (boolean)

Include the launch script section (requires an enrichment with a script). Default value: true. Property: ${hop.doc.script}.

sourceFolder (java.io.File)

Root folder where HOP diagram files (.hpl, .hwf) are searched. Defaults to the project base dir, following the Apache Hop convention where pipelines and workflows are stored directly in the project folder. Property: ${hop.sourceFolder}.

steps (boolean)

Include the steps (transforms/actions) section. Default value: true. Property: ${hop.doc.steps}.

titles (io.yupiik.hop.maven.documentation.DocTitles)

Section headings used by the AsciiDoc renderer.

transform2ArtifactMapping (Map)

Override mappings from transform plugin id to the artifact (artifactId or full groupId:artifactId:version coordinates) shipping it. Entries take precedence over the built-in table; the default rule is org.apache.hop:hop-transform-<id>.

Navigation