Skip to main content

Estructura del portal de documentación

Este portal centraliza la documentación de todos los repositorios de Liricus MAS 10. A continuación se explica cómo está organizado y cómo contribuir.

Organización general​

docs/
├── backend/                    ← Documentación de repos backend
│   └── {nombre_repo}/
│       ├── private/            ← Doc interna (para desarrolladores)
│       └── public/             ← Doc externa (para consumidores)
│           ├── openapi/        ← Specs OpenAPI (YAML)
│           └── api/            ← MDX generados (gen-api-docs)
│
├── frontend/                   ← Documentación de repos frontend
│   └── {nombre_repo}/
│       ├── private/            ← Doc interna (arquitectura, código)
│       └── public/             ← Doc externa (interfaces, pantallas)
│
└── tutorial/                   ← Guías generales del portal

Private vs Public​

Cada repositorio tiene dos secciones:

Private (interna)​

Documentación orientada a desarrolladores que trabajan en el código:

  • Arquitectura y decisiones técnicas
  • Flujos internos de los servicios
  • Estructura del proyecto y convenciones
  • Guías de setup y desarrollo local

Public (externa)​

Documentación orientada a consumidores del servicio/aplicación:

  • Backend: Specs OpenAPI, guías de consumo de endpoints, contratos
  • Frontend: Interfaces TypeScript, mapa de servicios por pantalla, guías de uso

OpenAPI (Backend)​

Los specs OpenAPI se ubican en {repo}/public/openapi/ y los MDX generados automáticamente en {repo}/public/api/.

Para regenerar la documentación de API:

yarn gen-api-docs
warning

Los archivos en las carpetas api/ son generados automáticamente. No editar manualmente — cualquier cambio se perderá al regenerar.

Cómo agregar un nuevo repo​

  1. Crear la carpeta del repo dentro de backend/ o frontend/
  2. Crear las subcarpetas private/ y public/ con sus _category_.json
  3. Si tiene OpenAPI, agregar el YAML en public/openapi/ y registrarlo en docusaurus.config.js
  4. Agregar los archivos .mdx con la documentación
  5. La sidebar se genera automáticamente desde la estructura de carpetas

Cómo agregar documentación​

Los archivos son .mdx (Markdown con soporte JSX). Cada archivo necesita un frontmatter mínimo:

---
sidebar_position: 1
title: Mi documento
---

# Título

Contenido...

Pipeline​

El pipeline de Bitbucket se encarga de:

  1. yarn install — instalar dependencias
  2. yarn gen-api-docs — generar MDX desde specs OpenAPI
  3. yarn build — generar el sitio estático
  4. Deploy a S3 + CloudFront

Los branches dev, qa y main despliegan automáticamente a sus respectivos ambientes.