Skip to content

How to build the HTML manuals from source using a container to build the documentation

Requirements

The OmegaT project provides a Gradle configuration to build the manuals using a container execution environment.

Theoretically, all the OCI-compatible container execution environments are supported. We tested both the Apache 2.0 licensed containerd and nerdctl and the non-free Docker Desktop, sold by Docker Inc.

OmegaT supports both nerdctl and docker command. If the nerdctl or docker commands are not in your path, all the documentation generation tasks will be skipped.

Container runtimes

The standards and FLOSS communities have provided users with a powerful set of container execution tools:

  • Runtime environment: containerd, kubernetes
  • Toolset: nerdctl, podman
  • Integrated environment: Rancher Desktop

Rancher Desktop

Rancher Desktop is an Electron-based application that wraps other tools while providing a simple user experience.

on macOS

On macOS, Rancher Desktop uses a virtual machine to run containerd. It also provides custom Lima machines with nerdctl.

Lima project provides Linux virtual machines for macOS, with built-in integration for nerdctl. There is an alternative project called colima (container for Linux on Mac) that provides container runtimes on macOS with minimal setup.

Rancher desktop supports both intel mac and arm mac.

on Windows

Rancher Desktop uses containerd on WSL2 and nerdctl on Windows.

on Linux

Rancher Desktop has requirements that are detailed here.

containerd/nerdctl and rootless mode on Linux

The OmegaT build system supports working in rootless mode.

Installation

Download the release files from the project.

bash
tar Cxzvvf /usr/local nerdctl-full-1.7.2-linux-amd64.tar.gz

And follow the instructions found here

Generating the documentation

Make sure the container execution environment is running before launching the building task.

generating the First Steps page (OmegaT 6.0 and later)

OmegaT 6.0 and later display a "First Steps" page in the Editor pane at launch. That page is built with the following command:

bash
$ ./gradlew firstSteps

The generated pages will be found in build/docs/greetings/<lang>/.

generating the HTML manuals and the available language index page

The HTML manuals and the available language index page are built with the following command:

bash
$ ./gradlew updateManuals

The manuals are found in build/docs/manual/. The available languages index page is at build/docs/manual/index.html.

generating the Instant Start Guides (OmegaT 5.7 and before)

OmegaT 5.7 and before display an "Instant Start" page in the Editor pane at launch. That page is built with the following command:

bash
$ ./gradlew instantStartGuides

The generated pages will be found in build/docs/greetings/<lang>/.

Under the hood

Document generation is done with the ant build configuration in the docgen container image. doc_src/docgen is a shell script that is launched from the Gradle build system. Arguments to docgen are the same as the arguments to ant described below.

See also: