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.
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:
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:
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:
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:
- docgen-docker: source for the docgen container