Documentation Build Pipeline Overview

This document explains how the Trento docs hub is assembled from local sources, fetched component documentation, generated metadata, and the custom UI bundle. It focuses on site assembly mechanics. For local preview commands, see the root README.adoc or Antora Documentation Site.

Overview

The docs hub build is driven by:

  • trento-docs-site/antora-playbook.yml

  • trento-docs-site/antora.yml

  • trento-docs-site/extensions/

  • trento-docs-site/scripts/

  • trento-docs-site-ui/build/ui-bundle.zip

The output of the build is written to trento-docs-site/build/trento-docs-site-public.

Source Inputs

The Antora build combines three kinds of documentation sources:

  • trento/ - Trento user-facing documentation that is also used for the official SUSE documentation output

  • content/ - project documentation maintained in this repository

  • upstream Trento repositories - component documentation fetched during the build

The UI for the rendered site is loaded from trento-docs-site-ui/build/ui-bundle.zip.

Build Flow

The high-level build flow is:

  1. Antora starts from trento-docs-site/antora-playbook.yml.

  2. The playbook loads content from the local repository with branches HEAD and latest.

  3. The collector extension clears the previous build output under trento-docs-site/build/.

  4. The collector clones the configured upstream component repositories into trento-docs-site/build/tmp_components/.

  5. trento-docs-site/scripts/generate-components.nav.js scans the fetched component repositories and generates trento-docs-site/build/gen_navigation/nav_components.adoc.

  6. The generated navigation file is scanned into modules/developer/partials, where it is included by the developer navigation.

  7. User-facing documentation from trento/adoc/ and trento/images/src/ is scanned into the user-guide module.

  8. trento-docs-site/scripts/generate-attributes-yaml.sh converts trento/adoc/generic-attributes.adoc into an Antora attributes file under trento-docs-site/build/adoc_variables/user-guide/.

  9. The root README.adoc and documentation under content/ are scanned into the developer module.

  10. The fetched upstream component repositories are scanned into per-component Antora modules such as agent, web, mcp-server, and wanda.

  11. Antora applies the configured extensions and renders the site with the custom UI bundle.

  12. The final site is written to trento-docs-site/build/trento-docs-site-public.

Generated Artifacts

During the build, the following generated directories are especially important:

  • trento-docs-site/build/tmp_components/ - shallow clones of upstream component repositories

  • trento-docs-site/build/gen_navigation/nav_components.adoc - generated navigation for the Components section

  • trento-docs-site/build/adoc_variables/user-guide/antora.yml - generated AsciiDoc attributes for the user guide

  • trento-docs-site/build/trento-docs-site-public/ - rendered site output

These directories are regenerated by the build and should be treated as build output, not hand-edited sources.

Antora Modules and Mapping

The docs hub does not render the source directories directly as-is. Instead, the build maps them into Antora modules:

  • trento/adoc/ becomes the user-guide module pages

  • content/ becomes the project documentation pages under the ROOT component

  • fetched upstream repositories become dedicated modules such as agent, web, helm-charts, and mcp-server

This mapping is defined in trento-docs-site/antora.yml.

Extensions Used During the Build

The playbook loads these Antora extensions:

  • @antora/collector-extension - orchestrates the cleaning, cloning, scanning, and generated-file steps

  • @sntke/antora-mermaid-extension - renders Mermaid diagrams

  • @antora/lunr-extension - generates search index data

  • ./extensions/edit-url.cjs - adds the Edit this page links used by the custom UI

The Edit URL Extension Workflow document explains the custom extension logic in detail.

Important Build Behaviors

  • The build requires network access because it clones upstream repositories during generation.

  • The docs hub includes both HEAD and latest, which is how the published site exposes the pre-release and current-release versions.

  • Component documentation is assembled into the site, but the source of truth remains the upstream repository.

  • UI source changes are not reflected in the site build until trento-docs-site-ui/build/ui-bundle.zip is rebuilt.