Ir al contenido

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.

Los enlaces a las fuentes apuntan a la rama dev del repositorio principal. Una compilación usa el commit que tenga extraído.

PáginaGenerada a partir de
Referencia de la APIapp/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 datosapp/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 Instalardocs/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

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:

  1. scripts/sync-adrs.mjs analiza 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.
  2. scripts/sync-openapi.mjs copia app/api/openapi.yaml a public/openapi.yaml, donde lo lee starlight-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.
  3. scripts/generate-schema-docs.mjs analiza app/schema.sql y escribe las páginas de developers/database/ (una visión general, una página por tabla y el visualizador del esquema) y el schema.json que lee el visualizador.
  4. scripts/sync-install-config.mjs analiza docs/install/config/aa.env.example y lo convierte en un partial de Starlight que importa la guía de instalación.
  5. scripts/sync-roadmap.mjs escribe la página de la hoja de ruta, que muestra el src/content/roadmap/roadmap.json curado de este repositorio. Es el único paso que no lee nada del repositorio principal.
  6. scripts/sync-screenshots.mjs copia las capturas de pantalla del producto que usa la página de inicio desde docs/screenshots/ a src/assets/screenshots/ para que Astro pueda optimizarlas.

Añadir otro paso de generación implica añadirlo a las dos cadenas prebuild y predev.