![\"../../../../_images/d1.png\"](\"https://technicalwriting.dev/_images/d1.png\")
2026 Oct 08
\nGiven a project that provides libraries in N different programming languages,\nthe docs site for that project often needs to interact with N or N+1 different\ndocumentation generators. This is because each programming language has its own\nAPI reference generator. While the libraries themselves may be loosely\ncoupled or decoupled from each other, the docs site often needs tighter\ncoupling in various ways: all pages should use the same fonts and colors, the\nin-site search UX should be consistent and comprehensive, etc.
\nThere doesn’t seem to be an established term for this kind of docs site, where\nyou’re attempting to wrangle the outputs from disparate docs generators into\none cohesive whole. Let’s call it a polyglot docs site for now. Maybe\nsomeone will come up with a better name in the future.
\nShort story long, polyglot docs sites feel like a sparsely explored frontier of\ntechnical writing, full of rattlesnakes and tumbleweeds. And perhaps a little\ngold, too.
\nIn terms of top-down strategy I can only think of 2 ways to structure a polyglot\ndocs site.
\nThe first strategy is to parse each API reference generator’s output and\ntransform it into markup that plays nicely with your main docs generator. For\nexample, in my first job I ingested Doxygen HTML as input, used XSLT (!!) to\ntransform it into simpler HTML fragments, and then used the raw directive to\npull the HTML fragments into my Sphinx site.
\nThe main drawback of the transformation approach boils down to losing out on\nthe expertise of the API reference generators:
\nTools like Doxygen, rustdoc, javadoc, etc. understand the details of their
respective languages much better than I do. With a custom transformation that\n“simplifies” the output, there’s a risk that I’m stripping out information\nthat users actually need. I.e. Chesterton’s fence.
These tools have put a lot of thought into the UX of API
references. For example, given a structured search query like\nvec -> usize, rustdoc’s search engine will only return functions that\ntake in a vec as an arg and returns usize.
Another drawback of transformation is that it goes against the grain of the\necosystem. Rust programmers are familiar with the rustdoc UI. Even if I could\ntheoretically create an API reference that’s superior in every way, I’m still\nasking my users to figure out a new and different UI that they won’t encounter\nanywhere else.
\nAnother example of the transformation approach is Breathe. You first run a\nDoxygen XML build, and then make that available as an input to the Sphinx\nbuild. In your reStructuredText you insert a directive like\n.. doxygenclass:: pw::Foo to indicate the place where the API reference for\npw::Foo should go. Breathe parses the info from the Doxygen XML and\ntransforms it into API reference content that Sphinx understands. This was the\nfoundation of C/C++ API reference content on pigweed.dev from 2022 to 2024.\nWe moved to the approach described in the next section for a few reasons:
One issue was slowness. I don’t remember the exact numbers but Breathe was
a significant bottleneck in our docs build. We went from something like 90\nseconds with Breathe to 60 seconds without it.
Another issue was too much glue code leading to silent failures. In addition
to marking up your headers with Doxygen comments, you have to remember to pull\nthe content into Sphinx via a directive like .. doxygenclass:: pw::Foo.\nOn quite a few occasions I saw SWEs make an honest effort to document their\ncode, but the documentation never actually got published, because they had\nforgotten the doxygenclass step.
The last issue was too much flexibility. Some docs contributors would order
their doxygenclass directives alphabetically on a single page. Others\nwould take a thematic approach. E.g. in the middle of a guide on how to foo\nthe bar, they would insert the API reference for pw::Foo.
The second strategy is to defer to the expertise of the API reference\ngenerators and publish their output as-is. This is what pigweed.dev does.\nUnder-the-hood, pigweed.dev is 3 separate docs sites cobbled together. We\ngenerate our C/C++ API reference with Doxygen, our Rust API reference with\nrustdoc, and everything else with Sphinx.
Architecture-wise, it’s a turducken. A chicken stuffed into a duck stuffed\ninto a turkey. Well, in the case of pigweed.dev it’s more like a chicken\n(Doxygen) and a duck (rustdoc) stuffed side-by-side into a turkey (Sphinx).
The obvious problem is that the subsites all look different from each other:
\nA Doxygen-generated page#
\n![\"../../../../_images/r1.png\"](\"https://technicalwriting.dev/_images/r1.png\")
A rustdoc-generated page#
\n![\"../../../../_images/s1.png\"](\"https://technicalwriting.dev/_images/s1.png\")
A Sphinx-generated page#
\nWith an obscene amount of !important flags I can make them look more similar\nto each other. And I plan on doing that. But no amount of CSS hacking can solve\nthe following more insidious problems:
\nIt’s hard to navigate from one subsite to another. E.g. from a
rustdoc-generated page there is no way to get back to the\npigweed.dev homepage.
The search UX is fragmented and incomplete. E.g. when using the in-site
search on a page generated by Sphinx, the search results do not include any\ncontent from rustdoc-generated pages.
It’s hard to link from one subsite to another. You end up relying on
hardcoded manual relative paths, which are brittle.
So, we’ve got 3 completely separate subsites that have no awareness of each\nother’s existence, and we somehow need to make them feel more connected. On\npigweed.dev we made some progress on this front by introducing a universal\nheader and comprehensive search.
\nOne header to rule them all, one search to find them
\nOne nav to map the path and breadcrumbs to remind them
Every page on the site now has the same top-level links, search, and\nbreadcrumbs UI. The theme selection also stays in sync across the\nsubsites.
\nThe Doxygen-generated page now:
\n![\"../../../../_images/d2.png\"](\"https://technicalwriting.dev/_images/d2.png\")
The rustdoc-generated one:
\n![\"../../../../_images/r2.png\"](\"https://technicalwriting.dev/_images/r2.png\")
And the Sphinx-generated one:
\n![\"../../../../_images/s2.png\"](\"https://technicalwriting.dev/_images/s2.png\")
Implementation-wise, it’s a bunch of postprocessing. During the Doxygen,\nrustdoc, and Sphinx builds we inject a <!-- pw-sentinel --> comment into\nevery page. The Doxygen and rustdoc builds run before the Sphinx build.\nWe have a Sphinx extension that hooks into the build-finished\nevent and replaces these comments with the full HTML, CSS, and JS for the\nheader. The extension has a lot of logic related to constructing the top-level\nlinks and breadcrumbs.
Within the universal header there is now a consistent UI for accessing the\nin-site search. The search opens as a modal, and results surface as you type.\nThe big win is that the search results are now comprehensive. I.e. all of our\nDoxygen, rustdoc, and Sphinx content is now indexed and surfaced in results:
\n![\"../../../../_images/pf.png\"](\"https://technicalwriting.dev/_images/pf.png\")
The 1st result comes from Doxygen, the 2nd and 3rd come from Sphinx, and the\n4th comes from rustdoc.#
\nThe real hero here is Pagefind. This library is a one-stop shop for all of\nour in-site search needs. We just point Pagefind to the output directory and it\ncreates the search index based off our built HTML. There are both allowlist and\ndenylist APIs for fine-tuning what content gets indexed. For the search UI we\nuse Pagefind’s default web components with a sprinkling of customization.\nThere’s a JS API if you want to completely customize the UX. Pagefind also\nseems to be doing cool things with web workers, WebAssembly, and on-demand\nloading of index chunks, but I couldn’t find a good overview of the internals\nin the official docs.
","headings":[{"level":1,"text":"The wild west of polyglot docs sites","id":"the-wild-west-of-polyglot-docs-sites"},{"level":2,"text":"Strategies","id":"strategies"},{"level":3,"text":"Transformation","id":"transformation"},{"level":3,"text":"Turducken","id":"turducken"}]}}![in sync](\"https://upload.wikimedia.org/wikipedia/en/e/e4/Nsync_%28album%29.png\"){kind=link}