The Wild West of polyglot docs sites

When a project ships libraries in several programming languages, the documentation site must reconcile outputs from many language-specific API generators. Two main strategies emerge: transform each generator’s output into the main docs format, or publish each generator’s output as-is and stitch the sites together. Transformation (for example, converting Doxygen XML into Sphinx content via Breathe or XSLT) centralizes presentation but risks stripping generator-specific semantics (rustdoc’s structured search is one example), forces users onto an unfamiliar UI, increases build complexity, and can create silent failures when contributors forget glue steps. That approach also added measurable overhead in one case - build time rising from roughly 60 to 90 seconds - and invited inconsistent organization across contributors.

The alternative defers to each generator’s expertise and composes a multi-subsite “turducken,” which preserves rich API UX but yields inconsistent look-and-feel, brittle cross-links, and fragmented search. Practical mitigations used on pigweed.dev include a universal header injected during postprocessing (generator builds insert placeholders; a final Sphinx extension replaces them with unified HTML/CSS/JS, synchronized breadcrumbs and theme controls) and a comprehensive search built with Pagefind that indexes the assembled HTML output so results surface across Doxygen, rustdoc, and Sphinx content. Pagefind’s web components, JS API, and on-demand indexing enable a single, modal search UI that returns mixed-source results.