Production Workflow: Generating the Real ODA SDK Docs

Audience: engineers working directly in the Pipeline repository who need to generate documentation for one or more of the real Open Design Alliance SDKs — not the mock example project used in Getting Started.

ude_projects/ in this repository contains configuration for the real SDKs, not just the mock example. As of 2026-08-14, listing ude_projects/ directly shows 15 SDK directories (BimNv, BimRv, Civil, Drawings, FacetModeler, IGES, Ifc, Kernel, Map, Mechanical, Prc, Publish, QIF, Step, Visualize) plus Architecture (the engine's own self-documentation project) and _analysis (not a document set). Counting ude_doc_config.json files under ude_projects/ gives 78 individual documents (one per SDK × language × HTML-or-Hugo combination that exists today) — also verified directly on 2026-08-14.

IMPORTANT

This page describes generation inside this repository, from source. A packaged binary distribution (e.g. the ODA release built from flude-oda-plugin) ships its own convenience scripts and its own documentation alongside the binary — none of which exist in the live Pipeline checkout. Do not mix the two: a command that works in a packaged distribution may not exist here, and vice versa.

---

What exists in this repository today

Per document directory (e.g. ude_projects/Kernel/kernel_api_cpp/):

• ude_doc_config.json, sidebar.toml — see Target Settings and Sidebar & Groups.
• generate_docs.bat — a thin wrapper that resolves the three config tiers and calls ude.cli. It prefers a repository-root .venv\Scripts\python.exe if one exists, falling back to plain python with PYTHONPATH pointed at engine\ otherwise (see Getting Started for both install paths). A repository-root .venv/ is not present by default — create one yourself (python -m venv .venv at the repo root, then pip install ./engine or poetry install inside it) if you want generate_docs.bat to use it directly.

Per SDK directory (e.g. ude_projects/Kernel/):

• generate_all.bat — iterates every subdirectory containing a generate_docs.bat and calls it, stopping on the first failure. 16 of these exist today (one per SDK, plus one for Architecture).

There is no repository-root run_all_sdks.bat, install.bat, or serve_and_open.bat. Those three scripts are generated or copied only when building the release bundle (see releases/make_release.py) — they do not exist anywhere under the live ude_projects/ tree or at the repository root.

---

Generating documentation

One document:

ude_projects\Kernel\kernel_api_cpp\generate_docs.bat

Writes output under .workdir/output/kernel_api_cpp/ (per the real output_base_dir in ude_projects/ude_global_config.json combined with that document's output_subdir) — see Architecture for the full path-resolution story.

One SDK, every language/format:

ude_projects\Kernel\generate_all.bat

Every SDK: there is no single script for this in the live repository. Iterate the SDK directories yourself, e.g. from PowerShell:

Get-ChildItem ude_projects -Directory | Where-Object {
    Test-Path (Join-Path $_.FullName 'generate_all.bat')
} | ForEach-Object { & (Join-Path $_.FullName 'generate_all.bat') }

Each SDK's generate_all.bat runs its documents sequentially. Running several SDKs' scripts in separate terminal windows at once is a reasonable way to parallelize, since each document is an independent ude.cli compile process with its own config — the same idea the packaged bundle's run_all_sdks.bat documents, just without a single wrapper script to do it for you here.

NOTE

On timing: the packaged release's own documentation (releases/ude_docs/docs/01-quick-start.md, 05-pipeline.md) reports approximate figures for a full 78-document run — on the order of several hours run sequentially, cut to roughly a quarter of that with a handful of generate_all.bat processes running in parallel across terminal windows. Those figures come from the packaged bundle's own measurements, whose exact date isn't recorded in the source document, and were not re-measured for this page — treat them as a rough order of magnitude for planning a full run, not a guarantee for this repository's current hardware or source tree size.

Before committing to a full run, check documentation coverage for a single document without paying for rendering:

python -m ude.cli audit --global-config ude_projects\ude_global_config.json --doc-config ude_projects\Kernel\kernel_api_cpp\ude_doc_config.json

See CLI Reference for the full audit contract and exit codes.

---

Building and viewing the combined Hugo site (Phase B)

Generating Markdown (Phase A, above) does not produce a browsable Hugo site by itself — that is a separate, later step over the files already written to .workdir/output/, driven by ude_hugo_site/build_site.py and ude_hugo_site/serve_site.py. See Architecture for exactly how a Hugo project's content/ is mounted from Phase A's output. Working directly from this repository, invoke the same two scripts manually with python, from ude_hugo_site/.

Related Docs

(Paths below are repository-root-relative.)

• user-docs/docs/architecture.md — the two-phase model these scripts implement
• user-docs/docs/adding-a-new-sdk.md — creating a new generate_docs.bat/ude_doc_config.json pair from scratch
• user-docs/docs/cli-reference.md — the ude.cli subcommands these scripts wrap