Apache Hop
Download
User manual 2.21.0 (pre-release)

Development Documentation

Edit this page

hop doc

hop doc writes documentation for a Hop project in Markdown format. It writes a page per pipeline and workflow with its diagram, and an index that links them. You can publish the Markdown with a tool such as MkDocs, or let hop doc write HTML as well.

hop doc is part of the Documentation plugin, which is not in the standard Hop client. Install it from the marketplace, where it is listed under Miscellaneous, or from the command line:

bash
hop marketplace install hop-misc-documentation

The same plugin has the Build documentation action, which does the same from a workflow.

Usage

  • Windows

  • Linux, macOS

shell
hop.bat doc -j my-project -t C:\docs\my-project
hop.bat doc -j my-project -t C:\docs\my-project -ip -in -im --generate-html
shell
./hop doc -j my-project -t /tmp/docs/my-project
./hop doc -j my-project -t /tmp/docs/my-project -ip -in -im --generate-html

Options

Option Description

-j, --project <name>

The project to document. See Which folder is documented.

-e, --environment <name>

Enable an environment, and document its project.

-t, --target-folder <folder>

The folder to write the documentation to. Required. It is created when it doesn’t exist.

-s, --source-folder <folder>

The folder to document, when no project is enabled.

-n, --project-name <name>

The name in the title of the index, when no project is enabled. The default is Hop.

-ip, --include-parameters

List the parameters of each pipeline and workflow.

-in, --include-notes

List the text of the notes of each pipeline and workflow.

-im, --include-metadata

Add an overview of the metadata elements of the project, such as connections and run configurations.

-gh, --generate-html

Also write an HTML file next to each Markdown file. The HTML index links to the HTML pages.

-rmmd, --remove-markdown

With --generate-html, remove the Markdown files once the HTML is written. Without --generate-html it does nothing.

All the -ip, -in, -im, -gh and -rmmd options are off unless you give them.

Run hop doc --help for the full list, which also has -pl, --environments and the other options of the hop command.

Which folder is documented

When a project is enabled, hop doc documents the home folder of that project, and uses the project’s name in the index. -s and -n are then not used.

A project is enabled with -j or -e, and otherwise the default project of your Hop configuration is used. The standard configuration has the default project as its default project, so name the project you want with -j.

-s and -n are only used when no project is enabled, for example when the Hop configuration has no default project.

What is written

The target folder gets the same subfolders as the project. For each pipeline and workflow, hop doc writes a page next to where the file is in the project: pipelines/load-orders.hpl becomes pipelines/load-orders-pipeline.md, and main.hwf becomes main-workflow.md.

docs/
├── index.md                          table of contents, linking every page
├── pipelines/
│   └── load-orders-pipeline.md
├── main-workflow.md
├── metadata/                         with --include-metadata
└── assets/
    ├── styles.css
    └── images/                       an SVG diagram per pipeline and workflow

Each page has the file name, the date the file was last changed and the diagram, plus the notes and the parameters when you ask for them.

With --generate-html, each .md file gets an .html file next to it, including index.html. With --remove-markdown as well, only the HTML files, the images and the styles remain.

Files that are already in the target folder stay, so remove the old documentation first when files were renamed or deleted in the project.