Case Study: Building This Portal

The very developer portal you are viewing right now is built on a transparent, self-documenting "dogfooding" architecture. This page details how UDE compiles its own Python source files to generate live API references nested inside these VitePress Guides.

---

🐕 The Dogfooding Concept

To prove that the Universal Document Engine can withstand high-load enterprise pipelines, we use UDE to document UDE. The Python core engine's modules (such as ude.cli and ude.orchestrator) are processed by our own compiler, generating the /api/ pages in this system.

This approach ensures:

• Constant Real-World Verification: Any parsing or rendering bugs in new commits are caught instantly during our own documentation build.
• Live Demos: Users can explore the live API Reference to see the exact visual output styles produced by the system.

---

📂 Local Workspace Directory Junctions

To allow developers to test self-compilation locally without messing up Git submodules or triggering circular reference loops, we configure Windows Directory Junctions:

Pipeline/ (Parent Repository)
├── engine/ (Core Codebase)
└── user-docs/ (This Submodule)
    └── engine ── [Directory Junction Link] ──> ../engine/

By linking user-docs/engine directly to the parent codebase folder, local compilers can inspect python docstrings dynamically without duplicating files or writing absolute, non-portable directory paths.

---

📑 Self-Configuration Block Walkthrough

The self-documenting pipeline is controlled by user-docs/ude_config_self.json. Here is the file in full:

{
    "project_name": "UDE API Reference",
    "src_dir": ["engine/ude"],
    "static_pages_dir": "./",
    "output_dir": "hugo-site/content",
    "incremental": true,
    "collector": {"type": "doxygen", "language": "python", "doxyfile_template": "Doxyfile"},
    "parser": {"type": "doxygen_xml"},
    "renderer": {"type": "hugo_markdown"}
}

Let's inspect its key parameters:

1. Source Directory

"src_dir": ["engine/ude"]

Points UDE at the local engine/ude Python source tree, reached via our directory junction, so the collector can walk it directly without duplicating files.

2. Source Collector

"collector": {"type": "doxygen", "language": "python", "doxyfile_template": "Doxyfile"}

Selects the Doxygen-based collector, tells it to parse Python (language: "python"), and points it at a Doxyfile template used to drive the underlying Doxygen invocation.

3. Parser & Output

"parser": {"type": "doxygen_xml"}

paired with the top-level

"output_dir": "hugo-site/content"

The doxygen_xml parser reads the Doxygen-generated XML AST into UDE's intermediate representation. Because this config sets a standalone output_dir rather than an output_subdir/output_base_dir pair, that field alone determines where rendered output is written.

4. Selecting the Hugo Markdown Renderer

"renderer": {"type": "hugo_markdown"}

Selects the Hugo Markdown renderer using the generic dispatch token "hugo_markdown", generating a cross-linked API Reference catalog under the configured output directory. Unlike some example configs elsewhere in this repository that set renderer.type to a concrete renderer class name, this self-config uses the generic token the renderer dispatch logic actually matches against.

---

⚙️ Build Order Orchestration (The Patch)

To prevent VitePress from wiping out our generated API catalog during production builds, our CI/CD pipeline enforces a strict Build Order Patch:

1. VitePress Compile: The command npm run docs:build compiles the human guides, outputting the SPA site to .vitepress/dist/.
2. Wipe Out: VitePress always wipes out its target folder before writing.
3. UDE Compile & Hugo Run: Only after VitePress finishes, the Python orchestrator compiles UDE's source docstrings and invokes Hugo to render the technical reference layer directly into .vitepress/dist/api/.

This build order ensures zero routing errors (404s) and delivers a seamless, unified developer portal experience containing both conceptual guides and technical references under a single hostname.