Writing documentation

Documentation lives in the Hop repository next to the code it describes, in docs/. Changing it is an ordinary pull request, which makes it one of the easiest ways to make a first contribution. The Documentation Contribution Guide on the website walks through forking the repository and opening that pull request.

The three manuals

Each is an Antora component with its own antora.yml and its own navigation tree:

docs/hop-user-manual: For people using Hop. Every transform, action and metadata type has a page here.
docs/hop-dev-manual: This manual: for people working on Hop or writing plugins for it.

There is no third manual: if a page tells someone how to use or operate Hop it belongs in the user manual, and if it tells someone how to build, extend or release Hop it belongs here.

Inside a manual the layout is always modules/ROOT/, with pages/ for the content, assets/images/ for images, nav.adoc for the navigation tree, and — in the user manual — templates/ with starting points for a plugin, sample or FAQ page.

Adding a page

Put the .adoc file under modules/ROOT/pages/, in the subfolder matching its section.
Give it the Apache License 2.0 header in an AsciiDoc comment block (//// … ////). Without it, Apache RAT fails the build.
Add a :description: line. It is used as the page summary and for search.
Add the page to modules/ROOT/nav.adoc, or it will not be published.
Link between pages with an xref macro, with the path relative to pages/ rather than to the current file: xref:database/index.adoc[Database plugins]. Across manuals, prefix the component name — manual or dev-manual — and pin the version with {page-component-version}@: xref:{page-component-version}@manual::pipeline/transforms/tableinput.adoc[Table input]. Without the version, Antora links to the latest stable release of the other manual, not to the version of the current page. A link to a page that is not in that release yet then breaks the website build, even though the pull request build passed. The pull request build rejects cross-manual xrefs without a version.

Documenting a plugin

A transform, action or metadata type gets a page in the user manual, and the plugin’s documentationUrl annotation attribute points at it:

java

@Transform(
    id = "DetectEmptyStream",
    documentationUrl = "/pipeline/transforms/detectemptystream.html")

The path is relative to the user manual on the website, and it is what the help button in the dialog opens. docs/hop-user-manual/modules/ROOT/templates/template-plugin.adoc is the starting point.

Anything a plugin developer needs — rather than a user — belongs in this manual instead.

Previewing the documentation locally

The manuals are published by the Antora playbooks in the apache/hop-website repository, not this one. Its run-website-local.sh script builds the website with the documentation from your Hop checkout and serves it.

Install Node.js 22, the version the pull request build uses.

Check out apache/hop-website next to your Hop checkout. The build reads ../hop, so the Hop checkout has to be in a folder named hop:

work/
├── hop/            your Hop checkout, on the branch you want to preview
└── hop-website/    a checkout of apache/hop-website, on main

In hop-website, run the script:
bash
```
./run-website-local.sh
```
It reads the working tree of ../hop, so uncommitted edits are included. When the server is up, the manuals are at http://localhost:4000/manual/latest/ and http://localhost:4000/dev-manual/latest/.

After the first build, ./run-website-local.sh --fast re-renders only the manuals, which takes seconds. Run a full build again when you delete or rename a page: --fast does not remove the pages it built before.

The pages are under latest, not next as on the website: the build only contains the version on your branch, so Antora publishes it as the latest one.

This page is a scaffold. Still to write:

The AsciiDoc conventions this project actually follows: one sentence per line, admonition usage, image sizing, how snippets under pages/snippets are included.
How a page reaches hop.apache.org, and how versioned manuals are cut at release time.