PIMP MY IDEBack to dispatches
October 11, 2026 / documentation systems / route integrity

One front door. Keep the native engines.

A multi-language project can have one docs site without forcing Doxygen, rustdoc, and Sphinx through the same mold.

Standardize the trip between references. Do not erase the language-specific search and navigation that make each reference useful.

The seam is a product surface

A project that ships libraries in several languages often inherits several documentation generators. Kayce Basques describes Pigweed's public docs as three sites joined together: Doxygen for C and C++, rustdoc for Rust, and Sphinx for the rest.[1]

That split is not a failure. Each generator understands its own language and user habits. Rustdoc can search by approximate function signature, including parameter and return types. Its manual documents queries such as usize -> vec and vec, vec -> bool.[3] Flattening that output into generic cards can discard working tools.

The hard part is not making three sites look alike. It is making the crossings predictable.

Transformation spends native knowledge

One route parses every generator's output and converts it to the main site's markup. This can unify the page structure, but the converter now owns details that the language tool already handled. Basques also reports a former Pigweed setup where the Breathe integration added build time and let documented symbols remain unpublished when a Sphinx directive was missing.[1]

The other route publishes each generator's output and joins the sites afterward. Pigweed injects a shared header into the built pages and uses one search entry point. This keeps the native pages, but it creates a new contract. Every output needs a route home, shared navigation, stable cross-links, and coverage in the common search index.

Index the built neighborhood

A post-build index can cross generator boundaries because it reads the final HTML instead of asking each generator to speak one source format. Pagefind's official guide says it runs after the static generator, writes a static search bundle, and accepts any set of static HTML files.[2]

That architecture solves one part of the problem. It does not prove that every subsite is included, that duplicate pages are excluded, or that a result lands on a stable route. Treat the search index as a release artifact. Record the input roots, page count, exclusions, and sample queries for each generator.

Test the crossings, not the paint

A shared font and header can hide a broken site boundary. Release checks should start inside each generated reference. Follow the home link. Search for one symbol from every engine. Open a cross-language link. Change the theme if the site offers one. Reload a deep link.

The switchyard below turns those crossings into four independent contracts. It is a teaching fixture. Selecting all four means the review template has all four sections. It does not prove that a real documentation build passed them.

Interactive teaching fixture

Docs switchyard

Traditional purpose: a platform selector, integration checklist, cross-site search preview, and release receipt. This rig uses one connected bus so each selected contract visibly feeds the same reader route.

BuildNative output
KeepEngine strengths
JoinReader routes
InspectRelease checks

Select an engine

The engine changes the sample result. The four contracts are independent release requirements.

Choose a documentation engine
Select route contracts for the review template
RUSTDOC / RUST2 OF 4 SELECTED

Reader route bus

Keep type-signature search in the native reference. Add a route home and include its pages in the common index.

Way homeSELECTED
Route mapSELECTED
Common indexOPEN
Deep replayOPEN
READER ROUTE BUS
Cross-site result sampleINDEX CONTRACT OPEN
RUSTVec::with_capacityNative result can keep its type-aware context while the common index supplies the route.
2 SECTIONS SELECTEDThe template still needs the common index and deep-link replay sections. No live build has been tested.
Copyable review template

Record each crossing

The switchyard fills this template from the selected teaching state. Replace every bracketed field with output from the real build before calling the route tested.

Sources read / October 11, 2026 UTC

Source log

Open the evidence boundary
  1. Kayce Basques, "The wild west of polyglot docs sites", October 8, 2026. This supplies the transformation and side-by-side publication strategies, the Pigweed implementation details, the Breathe experience, and the shared-header and comprehensive-search examples.
  2. Pagefind, "Getting Started with Pagefind", read October 11, 2026. This supports the post-build static index description and the claim that Pagefind works with a set of static HTML files.
  3. The rustdoc book, "Rustdoc search", read October 11, 2026. This supports the description and examples of name, path, parameter, return-type, and approximate type-signature search.
  4. Hacker News discussion, item 50019213, verified through the official item API and read October 11, 2026. We used it only as the current-interest signal.

Evidence boundary: Pimp My IDE read the named field report and official Pagefind and rustdoc documentation. We did not build Pigweed, inspect its current deployment, or compare every documentation generator. The switchyard is a browser-only teaching fixture and performs no documentation build or search.