Trento Documentation

This repository is the central documentation source for the Trento project. It brings together multiple documentation sources and publishes them to the Trento documentation hub and the official user-facing SUSE documentation at documentation.suse.com.

Repository Overview

Repository Directory Layout

Documentation Content

  • trento - user-facing Trento documentation used for both the docs hub and the official SUSE documentation

  • content - project documentation such as architecture, ADRs, coding standards, RFCs, templates, and internal notes

Build, UI, and Publishing Tooling

How This Repository Works

This repository assembles documentation from three sources:

  • trento/ contains the user-facing Trento documentation

  • content/ contains the project documentation maintained in this repository

  • upstream Trento component repositories provide additional documentation for the docs hub

The Antora playbook and extensions in trento-docs-site/ assemble the docs hub from these sources. The custom UI is maintained in trento-docs-site-ui/. The CI for the user-facing documentation intentionally mirrors SUSE/doc-unversioned with small Trento-specific adjustments, which keeps trento/ compatible with both the docs hub build and the SUSE documentation toolchain.

Documentation Sources

User-Facing Documentation

The trento directory is the single source of truth for Trento user-facing documentation. Its content is published in both the Trento docs hub and the official SUSE documentation.

Project Documentation

This repository contains project documentation such as:

These sources are maintained directly in this repository.

Component Documentation from Upstream Repositories

During the Antora build, documentation is fetched directly from upstream Trento project repositories and assembled into the docs hub under the Components section.

These sources usually live in the upstream repositories under docs/ or guides/. For example:

The build process adapts this upstream content to the Antora layout used by the docs hub. For example, documentation maintained in trento-project/web is published in the docs hub as /docs/web/README.html. The upstream repository remains the source of truth.

All changes to component documentation must be made in the source repository. They are picked up and included in the next Antora build of trento-project.io/docs.

Published Outputs

Docs hub

The Trento docs hub is published at trento-project.io/docs. It is built with Antora from the documentation sources described above.

Official SUSE documentation

The official SUSE documentation is published at documentation.suse.com. It is generated from the user-facing documentation in trento/.

Published Versions

Two published versions are currently exposed:

No older published versions are currently maintained in this repository.

Local Development

Where To Edit

Use this quick guide to decide where documentation changes belong:

  • Edit trento/ for Trento user-facing product documentation.

  • Edit content/ for project documentation such as architecture, ADRs, coding standards, RFCs, templates, and internal notes.

  • Edit the upstream component repository for component documentation published under Components in the docs hub.

    Examples:

Preview the Trento docs hub

From the repository root, this is the default way to preview the full docs hub workflow, including the current site assembly and published-output structure:

docker compose up trento-docs

Open http://localhost:3000 while the command is running.

The generated HTML is in trento-docs-site/build/trento-docs-site-public.

If you are working only in trento-docs-site/, you can use the manual Antora workflow described in Antora Documentation Site.

Docs hub previews consume trento-docs-site-ui/build/ui-bundle.zip. If you changed UI sources in trento-docs-site-ui/, rebuild the UI bundle first or the docs hub preview will still use the previous bundle.

Preview SUSE documentation

This preview uses a DAPS container maintained by the documentation team. It contains the official build toolchain used for the SUSE documentation output, so you can locally preview the same Trento user-facing sources both for the docs hub and for the official documentation published on the SUSE documentation site.

From the repository root, you can preview either the HTML output or the PDF output.

Preview SUSE documentation HTML

To build the DocBook HTML in a container and serve it on port 3001:

docker compose up daps-html-serve

Open http://localhost:3001 while the command is running.

The generated HTML is in trento/build/SLES-SAP-trento/html/SLES-SAP-trento. Each run clears trento/build/SLES-SAP-trento before rebuilding to avoid stale files.

Preview SUSE documentation PDF

To build the PDF output:

docker compose up daps-pdf-serve

Open http://localhost:3002/SLES-SAP-trento_en.pdf while the command is running.

The generated PDF is in trento/build/SLES-SAP-trento/SLES-SAP-trento_en.pdf. Each run clears trento/build/SLES-SAP-trento before rebuilding to avoid stale files.

Preview everything

Start both preview servers with one command:

docker compose up

To start all services in the background and skip compose logs:

bash dev-docs-env.sh

If your local Docker setup requires elevated permissions, run it with sudo.

Once it finishes, open:

Authoring Notes

For docs under content/, keep image files in content/images/.

This setup renders images correctly in both GitHub preview and Antora.

In pages that include images, add this fallback directive:

ifndef::imagesdir[:imagesdir: ../images]

Then reference images relative to imagesdir, for example:

image::release-branching.png[]
image::analytics/create-container.png[]

See a real example in content/internal-notes/analytics-setup.adoc.

The collector scan preserves subdirectories from content/images/; it does not flatten files.

Versioning and Release Workflow

These notes describe the documentation versioning and release workflow, including the roles of main and latest and the promotion flow for releases, partial release updates, and hotfixes.

Build and Automation Notes

These notes explain how the docs hub build, publication, and supporting automation work.