OCAH primarily uses AsciiDoc (.adoc) for structured documentation.

Native README files in GitHub which are intended to be read in isolation are written in Markdown (.md)

This approach provides:

In most cases documentation it is built in two formats: - Using Antora for the HTML site - Using asciidoctor-pdf for downloadable PDFs

Material intended only to be viewed via the website will not be built as downloadable PDFs

Documents are published in GitHub Pages at [https://docs.tenstorrent.com/tt-oca-harness/](https://docs.tenstorrent.com/tt-oca-harness/)

Downloadable PDFs are also accessible from the above location.

Generated register maps provide links from register names to their field tables, with each register listed in the contents and PDF bookmarks. The AsciiDoc partials contain a level-one address-map heading and level-two register headings. When including one, set leveloffset to the level of the containing section so both stay beneath it; for example, beneath === Detailed Register Map, use include::../regs/gen/adoc/example.adoc[leveloffset=+2].

The TRM PDF build checks every generated register map in the open register inventory against the assembled document. A missing map, missing register section, or section deeper than the contents or bookmark limit fails the build. Include new maps under their owning block and keep integration reference models labelled as such.

The TRM builds linked lists of figures and tables, including generated register tables. Prefer an explicit block title and stable anchor for each authored figure or table, and reference that anchor where the explanatory text needs it. Use automatic cross-reference text instead of hard-coded figure or table numbers. Untitled figures use their alternative text; untitled tables use their containing section and, for register tables, the table’s purpose. Do not add automatic section-local figure/table lists or prose that only repeats a caption. Keep useful explanations and explicit cross-references.

End each block reference with "Memory Map and Register Reference", containing "Memory Map" (address placement and access rules) and "Detailed Register Map" (register definitions or links to the owning blocks). Keep subsystem summaries and peripheral register ownership distinct.

tools/doc/block_catalog.rb numbers and indexes blocks across the PDF book. The PDF numbers sections four levels deep, down to each subsystem chapter; tools/doc/section_xref_numbering.rb makes a cross-reference to a deeper section render its title instead of a number the heading does not show. The Antora extensions tools/doc/block-captions.js and tools/doc/block-indexes.js number blocks within each TRM topic and assemble the HTML indexes. Keep these extensions enabled in both the standalone and combined playbooks. Other documentation products retain their own captions.

Document updates are made by pushing changes to main.

The CI process deploys to the published site on all pushes to main (see .github/workflows/doc.yml).

Documentation may also be built locally for development. Follow the instructions here to install Asciidoctor and Antora.

Alternatively, to avoid the need to install local tools, the toolchain is available as container images - set it up as described in the container quick start.

The two commands below may be executed from the root of the checked out repository. They generate the built material in subfolders under each book.

Once the documents are built they can be staged with the command below. This builds the whole site in the location shown.

The build can then be served locally for viewing with the commands below.

This will generate the documentation, and then serve it on http://localhost:8000/. You will then be able to access it in your web browser.

For a preview that opens at the TRM, run make doc-trm-serve. The TRM HTML build includes the other guides so links to Home, integration details, and programming procedures resolve locally. The container command scripts/docker-run.sh doc-html trm builds the same set of guides. If port 8000 is occupied, use make doc-trm-serve OCAH_TRM_SERVE_PORT=8001.

All images are stored in the repository at doc/trm/assets regardless of which document they appear in. This allows images to be reused across documents without requiring a copy for each document.

Images are copied from this location to the assets directory of every document as part of the build process.

Any image can then be embedded in an Asciidoc document with:

On the HTML site, click an unlinked block image to open the image viewer. Use the mouse wheel to zoom and drag the image to pan. The toolbar provides zoom in, zoom out, actual size (1:1), and reset controls. Keyboard users can focus an image and press Enter or Space to open it, use the up/down arrow keys to zoom, and press Escape to close the viewer.

Kroki renders text-based diagrams (Mermaid, PlantUML, D2, and others) into images at build time. By default the asciidoctor-kroki Antora extension sends diagram source to the public https://kroki.io service. Running a local Kroki server avoids the network round-trip, works offline, and keeps diagram source off an external service.