La documentación de proyectos que ofrecen bibliotecas en múltiples lenguajes de programación, conocidos como sitios de documentación políglota, enfrenta el desafío de integrar generadores de API dispares, como Doxygen, rustdoc y Sphinx, en una experiencia de usuario cohesiva. Este artículo técnico explora dos estrategias principales para lograr esta unificación: la transformación y la arquitectura de subsitios independientes.
La primera estrategia, la transformación, implica parsear la salida de cada generador para adaptarla al formato de un generador principal. Sin embargo, este método presenta riesgos significativos: puede eliminar información técnica crítica generada por las herramientas especializadas y obliga a los usuarios a abandonar la interfaz familiar de sus lenguajes de programación, como la de rustdoc. Además, introduce cuellos de botella en el tiempo de construcción y aumenta la complejidad del código.
La segunda estrategia, descrita como un 'turducken', consiste en publicar la salida de cada generador de API de forma independiente y unirlas mediante una capa de presentación unificada. El caso de estudio de pigweed.dev ilustra esta aproximación, que genera sitios separados para C/C++ (Doxygen), Rust (rustdoc) y otros (Sphinx). Aunque esto resulta en una fragmentación inicial en la navegación y la búsqueda, la solución propuesta incluye la inyección de un encabezado universal y la implementación de una búsqueda integral mediante la librería Pagefind. Esta última indexa todo el contenido generado por los distintos sistemas, permitiendo una búsqueda transversal que resuelve la discontinuidad de la experiencia de usuario entre los subsitios.