Referencia
La mayor parte de esta sección se genera al compilar el sitio: la referencia de la API, las páginas del esquema de la base de datos, la tabla de configuración de instalación y los registros de decisiones de arquitectura (ADR). Unas pocas páginas se escriben a mano:
- Pipeline de previsualización 3D: cómo se renderizan los pósters, los turntables, las sprite sheets y las vistas de referencia de los assets 3D.
- API por lotes de la herramienta de sprites: cómo controlar el diseño de frames, las etiquetas y las variantes de la herramienta de sprites a través de la API HTTP, desde un script o un trabajo por lotes. Las exportaciones se quedan en el navegador.
Cuando una página generada es incorrecta, corrígela donde empieza el
problema. En las páginas de referencia respaldadas por el repositorio OSS,
eso significa la especificación OpenAPI, las migraciones de la base de
datos, la plantilla de configuración o el ADR del repositorio principal. La
hoja de ruta sale de src/content/roadmap/roadmap.json, que se mantiene a
mano en este sitio; una comprobación programada de desviaciones lo compara
con las versiones e hitos de GitHub registrados en los datos del sitio. Los
problemas de maquetación o de análisis corresponden a los scripts
generadores de este sitio.
Fuentes
Sección titulada «Fuentes»Los enlaces a las fuentes apuntan a la rama dev del repositorio
principal. Una compilación usa el commit que tenga extraído.
| Página | Generada a partir de |
|---|---|
| Referencia de la API | app/api/openapi.yaml: copiado al sitio por sync-openapi.mjs y renderizado por starlight-openapi. Los tipos de API del servidor Go se generan a partir del mismo archivo con oapi-codegen en el repositorio principal; el sitio no lo ejecuta. |
| Esquema de la base de datos | app/schema.sql, un volcado solo del esquema de una base de datos construida a partir de las migraciones: analizado por generate-schema-docs.mjs |
| Tabla de configuración de instalación en Instalar | docs/install/config/aa.env.example: analizado por sync-install-config.mjs. Solo las variables sin comentar se convierten en filas; los ajustes opcionales comentados no se listan. |
| Hoja de ruta (en inglés) | src/content/roadmap/roadmap.json en el repositorio de este sitio, mantenido a mano: sync-roadmap.mjs escribe la página que lo muestra. Una comprobación programada lo compara con las versiones e hitos de GitHub registrados en los datos del sitio. |
| Decisiones de arquitectura (barra lateral) | docs/adr/*.md: validadas y copiadas por sync-adrs.mjs |
Regeneración
Sección titulada «Regeneración»pnpm build y pnpm dev ejecutan primero los pasos de generación, a
través de los scripts prebuild y predev de package.json, de modo que
las páginas generadas reflejan el repositorio principal tal como estaba
extraído en ese momento. Ejecutar astro build o astro dev directamente
se los salta. Los pasos se ejecutan en este orden:
scripts/sync-adrs.mjsanaliza y valida el frontmatter YAML de cada ADR (docs/adr/*.md), comprueba las referencias cruzadas entre ADR y escribe las páginas de los ADR junto con los datos que usa el catálogo.scripts/sync-openapi.mjscopiaapp/api/openapi.yamlapublic/openapi.yaml, donde lo leestarlight-openapi, haciendo de paso que los enlaces relativos de la especificación apunten a los archivos fuente correspondientes. La copia también se publica en/openapi.yaml.scripts/generate-schema-docs.mjsanalizaapp/schema.sqly escribe las páginas dedevelopers/database/(una visión general, una página por tabla y el visualizador del esquema) y elschema.jsonque lee el visualizador.scripts/sync-install-config.mjsanalizadocs/install/config/aa.env.exampley lo convierte en un partial de Starlight que importa la guía de instalación.scripts/sync-roadmap.mjsescribe la página de la hoja de ruta, que muestra elsrc/content/roadmap/roadmap.jsoncurado de este repositorio. Es el único paso que no lee nada del repositorio principal.scripts/sync-screenshots.mjscopia las capturas de pantalla del producto que usa la página de inicio desdedocs/screenshots/asrc/assets/screenshots/para que Astro pueda optimizarlas.
Añadir otro paso de generación implica añadirlo a las dos cadenas
prebuild y predev.