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 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.

docs/hop-tech-manual

Deeper technical notes that are neither user-facing nor about contributing.

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

  1. Put the .adoc file under modules/ROOT/pages/, in the subfolder matching its section.

  2. Give it the Apache License 2.0 header in an AsciiDoc comment block (//// …​ ////). Without it, Apache RAT fails the build.

  3. Add a :description: line. It is used as the page summary and for search.

  4. Add the page to modules/ROOT/nav.adoc, or it will not be published.

  5. 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, dev-manual or tech-manual: xref:manual::pipeline/transforms/tableinput.adoc[Table input].

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:

@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.

This page is a scaffold. Still to write:

  • Building the documentation locally to preview it. The Antora playbook lives in the Hop website repository, not this one; the exact steps need writing down.

  • 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.