Skip to content

Docs Tooling

Andromeda builds its generated C++ API reference through the C# command-line tool in Programs/Tools.

Build the tool:

dotnet restore Programs\Tools\Tools.csproj
dotnet build Programs\Tools\Tools.csproj -c Release --no-restore

Run the generated docs pipeline from the repository root:

.\Programs\Tools\bin\Release\net10.0\tools.exe docs build-doxygen
.\Programs\Tools\bin\Release\net10.0\tools.exe docs build-api-ref
.\Programs\Tools\bin\Release\net10.0\tools.exe docs build-api-graph
.\Programs\Tools\bin\Release\net10.0\tools.exe docs build-zensical
uv run zensical build --strict

The docs tool discovers the repository root by walking upward until it finds Andromeda.uproject. Each command also accepts --repo-root <path> for CI or scripted use.

Commands

docs build-doxygen requires doxygen on PATH. It runs docs/Doxyfile and writes Doxygen XML under Intermediate/Docs/Doxygen/xml.

docs build-api-ref reads Doxygen XML and generates Markdown API pages under docs/api-reference.

docs build-api-graph reads Doxygen XML and generates the aggregate project-level function call graph JSON under docs/api-graphs/assets. Doxygen provides the symbol database, source ranges, inheritance metadata, and fallback references; the graph builder owns source-text call inference and Unreal-aware relationships. The command also invokes Node with pinned elkjs from package-lock.json to precompute graph layout before the JSON is written. The API Graphs Markdown page and interactive browser viewer are checked in under docs/api-graphs/index.md and docs/javascripts.

The ownership split is intentional:

  • The C# tool owns graph semantics: nodes, edge kinds, source locations, and inferred relationships.
  • Programs/Tools/Docs/FunctionCallGraph contains the graph-only implementation: FunctionCallGraphBuilder owns graph construction order, FunctionCallGraphModel owns the internal node and edge model, and the rule-specific *Edges files own individual inference rules.
  • FunctionCallGraphWriter stays in Programs/Tools/Docs because it is the command-facing docs service; it owns only the generated JSON shape and connected-node filtering.
  • The checked-in Markdown owns page structure and Zensical-styled controls.
  • The JavaScript viewer owns presentation and interaction: layout, class colors, edge strokes, pan/zoom, search, selection, highlighting, and control behavior.
  • CSS owns visual styling that can be expressed declaratively, such as toolbar layout and edge dash patterns.

Graph edge sources:

  • CppSourceCall: C++ calls inferred from source text, including same-class calls such as SetFocusedObject(...), explicit qualified calls such as IAndromedaFocusCandidateProviderInterface::IsFocusCandidateProvider(...), and calls through project-typed members or locals such as ScannerScreen->ShowIdle().
  • CppCallbackBinding: function-address callback registrations such as EnhancedInputComponent->BindAction(..., &AAndromedaCharacter::MouseLookInput).
  • DoxygenReference: fallback function references emitted by Doxygen XML when no source-call edge has already been added. Constructor references are ignored unless the source text contains actual constructor-call syntax, because Doxygen can otherwise link type mentions in casts/templates to constructors.
  • CppVirtualDispatch: possible override targets for ordinary virtual calls. Doxygen provides reimplementedby metadata, and the graph expands an unqualified or this-> call to include child overrides while keeping the base-call edge. Explicit base calls such as Super::Foo() or AParent::Foo() are not expanded.
  • UnrealExecuteCall and UnrealExecuteImplementation: Unreal interface dispatch through IAndromeda...::Execute_Foo(...) and matching Foo_Implementation methods.
  • UnrealDelegateBinding: Unreal delegate flow. Binding sites such as OnSomething.AddDynamic(..., &ThisClass::Handler) link to their handlers, and matching OnSomething.Broadcast() sites link to the functions where those subscriptions are made.

docs build-zensical reads Doxygen XML, injects generated API navigation into zensical.template.toml, and writes zensical.toml. It does not run Zensical; run uv run zensical build --strict after this command.

The committed Zensical config is zensical.template.toml. The generated zensical.toml is ignored and should not be committed.

Generated API Markdown, API graph JSON assets, Doxygen XML, and docs-site output are build outputs. Do not commit docs/api-reference/, docs/api-graphs/assets/, Intermediate/Docs/, docs-site/, or zensical.toml.

CI

The Azure Static Web Apps pipeline builds the generated docs site on a Microsoft-hosted ubuntu-latest agent by building Programs/Tools, running the docs subcommands, running the strict Zensical build, and deploying docs-site with AzureStaticWebApp@0.

Docs generation no longer requires Unreal Editor, an AndromedaEditor build, the self-hosted Windows agent, or Graphviz. The pipeline installs the pinned .NET 10 SDK, Node.js, Doxygen, and uv before building the site.