Antylogic
Probar demoAcceso app

399 guías operativas

Secciones de Docs
DocsDocumentación y ayuda
Dispositivo

Sincronizar el bundle de docs generado

Empaqueta la documentación generada en el bundle del backend que usan las páginas públicas de Docs y la pantalla autenticada de Documentación de la app. La sincronización escribe articles.json y manifest.json, y puede reconstruir el directorio de media de documentación de runtime cuando se fija DOCS_ASSETS_OUTPUT.

En este artículo

Usa esta guía cuando los operadores de release o de documentación necesiten que el mismo corpus de guías generado aparezca en las páginas públicas de Docs de la landing y dentro de la app autenticada de Antylogic.

La sincronización empaqueta un bundle generado existente. No crea, aprueba, edita ni publica artículos individuales.

Para el destino de documentación de ES, valida con peticiones de Docs en español después de volver a ejecutar la sincronización desde la fuente generada más reciente.

Antes de empezar

  • Acceso por shell o CI a un checkout que contiene backend/scripts/sync-docs-content.mjs.
  • Node.js está disponible para node backend/scripts/sync-docs-content.mjs.
  • Existe una fuente soportada mediante DOCS_GENERATED_SOURCE, DOCS_SOURCE_DIR o el frontend/landingpage/src/content/wiki-generated-data.ts por defecto.
  • El proceso puede escribir en DOCS_CONTENT_OUTPUT o en el directorio backend/docs-content por defecto.
  • Si DOCS_ASSETS_OUTPUT está fijado, apunta a un directorio seguro que pueda borrarse y recrearse.
  • Para backend/scripts/prepare-docs-content.sh con una ref remota de docs, git y las credenciales configuradas del repositorio de docs están disponibles.
  • No se requiere ningún rol ni permiso de la app de Antylogic porque es una operación de shell o CI.

Instrucciones

  1. 1.

    Selecciona la fuente

    Elige el bundle de documentación generado que se va a empaquetar. Usa DOCS_GENERATED_SOURCE para un fichero explícito, DOCS_SOURCE_DIR para un checkout o directorio de build de docs generados, o deja ambos sin fijar para usar frontend/landingpage/src/content/wiki-generated-data.ts.

  2. 2.

    Ejecuta la sincronización

    Ejecuta node backend/scripts/sync-docs-content.mjs para un empaquetado local directo, o backend/scripts/prepare-docs-content.sh [entorno] cuando la preparación del despliegue deba resolver primero una ref de docs.

  3. 3.

    Revisa el bundle

    Comprueba articles.json y manifest.json antes del empaquetado de release. Confirma version, generated_at, locales, platforms, los metadatos de la fuente y el puntero articles_file.

  4. 4.

    Gestiona los assets de media

    Fija DOCS_ASSETS_OUTPUT solo cuando deban empaquetarse capturas o clips de documentación. La sincronización reinicia ese directorio y copia la fuente resuelta de assets de docs cuando existe; sin él, solo se escriben los ficheros de contenido.

  5. 5.

    Verifica los Docs públicos

    Abre /docs, /manual o /wiki y confirma que la página carga desde el bundle del backend. Comprueba GET /api/public/docs?locale=es&platform=web&theme=light para article_count y sections.

  6. 6.

    Verifica los Docs de la app

    Usa la sesión de ES de Grupo Marea Demo para el usuario demo. Comprueba GET /api/app/docs?locale=es&platform=web&theme=light, después abre antylogic://docs y confirma que la pantalla de Documentación carga el mismo índice.

Validaciones y límites

  • El comando termina sin error de fuente no encontrada ni de parseo.
  • articles.json y manifest.json existen bajo la raíz de salida de contenido seleccionada.
  • manifest.json contiene articles_file: articles.json.
  • locales incluye los idiomas de documentación esperados; el bundle commiteado contiene actualmente en y es.
  • platforms es mobile, tablet y web.
  • Las respuestas de índice de docs pública y autenticada exponen article_count y sections tras la sincronización.
  • La media de documentación, cuando está presente, se resuelve a través de /api/public/docs/assets/... o /api/app/docs/assets/....
  • Trata el bundle commiteado como potencialmente más antiguo que la última actualización de documentación hasta que la sincronización se vuelva a ejecutar desde la fuente generada más reciente.

Resultado esperado

Tras la verificación, las superficies de Docs pública y autenticada leen el mismo bundle de documentación del backend, y los assets de runtime se copian al directorio de salida configurado o se omiten intencionadamente.

Artículos relacionados