Adding a New SDK or Document

Audience: maintenance engineers adding a new SDK, or a new language/format variant of an existing SDK, to ude_projects/.

This walks through the same three-tier structure covered piece by piece in Target Settings and Sidebar & Groups, assembled here as one end-to-end example. The config snippets below follow the shape of real, currently-shipping projects (e.g. ude_projects/Kernel/kernel_api_cpp/), with a placeholder SDK name so you can copy it directly.

---

1. Create the SDK directory and ude_sdk_config.json

ude_projects/MyNewSDK/ude_sdk_config.json

{
    "product_name": "MyNewSDK",
    "docs": [
        {
            "type": "api",
            "id": "mynewsdk_api_cpp",
            "title": "C++ API Reference",
            "lang": "cpp",
            "path": "mynewsdk_api_cpp",
            "main_page": "mynewsdk_api_ref.html"
        }
    ]
}

product_name is used by the ODA renderers for each page's title; add one docs[] entry per language/format variant you plan to ship (a real SDK typically has one entry per language, times two if it also ships a Hugo variant — see ude_projects/BimNv/ude_sdk_config.json for a live 8-entry example covering four languages × HTML/Hugo).

2. Create the document directory

ude_projects/MyNewSDK/mynewsdk_api_cpp/

2.1 ude_doc_config.json

{
    "project_name": "MyNewSDK C++ API Reference",
    "short_project_name": "MyNewSDK",
    "src_dir": ["../../../workspace/sdk_sources/MyNewSDK/Include"],
    "static_pages_dir": "./",
    "incremental": true,
    "max_workers": 8,
    "collector": {
        "type": "CppDoxygenCollector",
        "language": "cpp",
        "file_patterns": ["**/*.h", "**/*.hpp"]
    },
    "parser": {
        "type": "CppDoxygenParser"
    },
    "renderer": {
        "type": "oda_html"
    },
    "output_subdir": "mynewsdk_api_cpp"
}

Notes, cross-checked against engine/ude/orchestrator.py:

• renderer.type must be one of the nine dispatch tokens the engine actually recognizes: html, static_html, oda_html, hugo_markdown, markdown, hugo, oda_hugo_markdown, oda_markdown, oda_hugo — see Target Settings. Real ODA projects use oda_html for the corporate-styled static HTML variant and oda_hugo_markdown for the Hugo variant, not the base html/hugo_markdown tokens, and never a concrete renderer class name like CppHtmlDefaultRenderer.
• src_dir must be a JSON array, even for one path.
• Do not add a groups or sidebar key anywhere in this file — see step 2.2.

2.2 sidebar.toml

Both [[sidebar]] and [groups] are mandatory here, with no default or fallback of any kind — see Sidebar & Groups for the full contract:

[[sidebar]]
type = "api_reference"
label = "API Reference (C++)"
url = "index.html"

[groups]
namespace_level = [
    "Classes",
    "Fields,_Structures_and_Enums",
    "Functions",
    "Types",
]

namespace_level is the only permitted key inside [groups] — there is no class_level. The list above matches the taxonomy used across the real C++ SDKs in this repository; pick group names that fit your own SDK's structure. There is nothing to inherit from anywhere else, so write it out in full.

2.3 generate_docs.bat

@echo off
chcp 65001 >nul
setlocal
pushd "%~dp0"
set "GLOBAL_CONFIG=..\..\ude_global_config.json"
set "SDK_CONFIG=..\ude_sdk_config.json"
set "DOC_CONFIG=ude_doc_config.json"
set "UDE_PYTHON=%~dp0..\..\..\.venv\Scripts\python.exe"
if not exist "%UDE_PYTHON%" (
    set "PYTHONPATH=%~dp0..\..\..\engine;%PYTHONPATH%"
    set "UDE_PYTHON=python"
)
"%UDE_PYTHON%" -m ude.cli --global-config "%GLOBAL_CONFIG%" --sdk-config "%SDK_CONFIG%" --doc-config "%DOC_CONFIG%"
if %errorlevel% neq 0 (
    popd
    exit /b 1
)
popd
endlocal

This is the same real script already shipping in every document directory (e.g. ude_projects/Kernel/kernel_api_cpp/generate_docs.bat) — copy it verbatim, no per-project edits needed beyond the relative paths already shown.

2.4 Doxyfile (optional)

Only needed if you require Doxygen options the engine's own Doxyfile template (engine/ude/templates/Doxyfile) and your collector config don't already cover.

3. Create ude_projects/MyNewSDK/generate_all.bat

@echo off
chcp 65001 >nul
setlocal enabledelayedexpansion
pushd "%~dp0"

for %%i in ("%~dp0.") do set "SDK_NAME=%%~nxi"
echo ============================================================
echo   UDE: Building all %SDK_NAME% Documentation
echo ============================================================

for /d %%p in (*) do (
    if exist "%%p\generate_docs.bat" (
        echo [BUILD] Processing project: %%p
        call "%%p\generate_docs.bat"
        if !errorlevel! neq 0 (
            echo [ERROR] Build failed for project: %%p
            popd
            exit /b 1
        )
    )
)
popd

This is the same pattern already used by every real SDK's generate_all.bat (e.g. ude_projects/Kernel/generate_all.bat) — it simply calls every subdirectory's generate_docs.bat in turn. See Production Workflow for how this fits into generating (and, separately, browsing) documentation for the whole repository.

4. Check coverage before a full build

python -m ude.cli audit --global-config ude_projects\ude_global_config.json --doc-config ude_projects\MyNewSDK\mynewsdk_api_cpp\ude_doc_config.json

Exit code 2 means measured coverage is below GlobalConfig.coverage_threshold — see CLI Reference for the full audit contract.

Related Docs

(Paths below are repository-root-relative.)

• user-docs/docs/target-settings.md — full ude_doc_config.json key reference
• user-docs/docs/sidebar-and-groups.md — full sidebar.toml reference
• user-docs/docs/production-workflow.md — running the scripts created above