Reader's Guide: Browsing an Already-Built Site

Audience: engineers who just want to read an already-generated documentation site — not generate it, not maintain its configuration. If you need to build or regenerate anything, see Production Workflow instead.

---

Portal structure and navigation

At the root of a fully-built site sits the Portal — a landing page linking to every generated SDK (BimNv, Kernel, Ifc, and so on). Each SDK link leads to that SDK's own landing page, and from there to its API documentation in whichever programming languages were generated for it (C++, C#, Java, Python).

Each language/SDK combination (for example, the Python API reference for Ifc) is built as an independent Hugo project; a later build step (see Architecture) stitches them into one navigable tree so links between SDKs resolve correctly.

The sidebar on the left of any page comes directly from that document's own sidebar.toml — both the navigation entries ([[sidebar]]) and the folder grouping of classes/namespaces/etc. ([groups]). See Sidebar & Groups if you're curious how that file works; as a reader you don't need to touch it.

Two output formats, same content

Many SDKs ship two parallel variants of the same underlying API content:

• <sdk>_api_<lang> — standalone static HTML in the ODA house style (renderer.type: oda_html or html). Self-contained; nothing else needs to build.
• <sdk>_api_<lang>_hugo — the same API content rendered as Hugo Markdown (renderer.type: oda_hugo_markdown or hugo_markdown), which becomes part of the combined Portal site described above.

The two are generated independently and can drift briefly out of sync if only one was rebuilt recently — they are not guaranteed byte-identical at every moment, only equivalent in content.

If you spot a documentation problem

Flude extracts documentation directly from Doxygen-style comments in the SDK's own source code. If you find a typo, a missing parameter description, or an incorrect type on a generated page, the source of the problem is almost always the SDK's source comments, not the site itself — see Commenting Rules for exactly which tags Flude recognizes and how it extracts them, and Exclusion Gates if something you expected to see is missing entirely (it may have been deliberately filtered, e.g. via @internal). Fix the doc comment in the SDK repository via a normal pull request; the correction appears automatically on the next build.

Offline viewing

A fully-built site is completely static. In this repository, the combined output lands in .workdir/output/_hugo_site_dist/ (see Architecture for how it gets there); a packaged binary distribution puts the equivalent output under its own working directory instead. Either way, once built you don't need Python, Doxygen, or Hugo to view it — any static file server pointed at that directory works, e.g. python -m http.server, or the repository's own ude_hugo_site/serve_site.py.

Related Docs

(Paths below are repository-root-relative.)

• user-docs/docs/architecture.md — how the Portal and per-SDK builds fit together
• user-docs/docs/commenting-rules.md — what a doc comment needs to say to show up correctly
• user-docs/docs/exclusion-gates.md — why an entity you expected to see might be missing