oba-docs-poc

PoC de flujo completo de la plataforma de documentación de Odoo by Adhoc — task 71947, subtarea de #52201.

No es un benchmark de features: las features se compararon el 04/08. Esto prueba el loop de trabajo real contra la arquitectura que fijaron el ADR 0004 (árbol único, la versión es metadata) y el ADR 0005 (cada audiencia es un build).

La idea en una línea

content/  ──  tools/build.mjs  ──►  árbol generado  ──►  plataforma  ──►  dist
 (fuente)      (preprocesador)       (por target)         (build)      (dos sitios)

Cuatro targets sobre el mismo árbol fuente — así se compararon en serio:

Target	Consumidor	Dónde
docusaurus (default)	Docusaurus 3 + Faster	site/
starlight	Astro 7 + Starlight 0.41	site-starlight/
mkdocs	MkDocs 1.6 + Material 9.7 (un build por versión, patrón mike)	site-mkdocs/
rspress	Rspress 2 (@rspress/core), multiVersion nativo con versión sintética de default	site-rspress/

content/ es lo único que se edita a mano. Todo lo que aparece bajo site/docs/, site/versioned_docs/, site/relacion/ y dist/ es artefacto generado y está en .gitignore.

Cómo levantarlo

npm install && npm --prefix site install

# Un sitio en modo desarrollo, con hot-reload sobre content/
npm run gen:publico && npm --prefix site start      # http://localhost:3000

# Los dos sitios construidos, para compararlos
npm run build:publico && npm run build:interno
npx --prefix site docusaurus serve --dir dist/publico --port 3000
npx --prefix site docusaurus serve --dir dist/interno --port 3001

Comandos

Comando	Qué hace
npm run lint	Valida el árbol fuente sin emitir nada. Falla si dos archivos matchean el mismo (slug, versión)
npm run gen:publico / gen:interno	Emite el árbol generado para una audiencia
npm run build:publico / build:interno	Preprocesador + build de Docusaurus a dist/<audiencia>
node scripts/verificar.mjs	Verifica los criterios de aceptación del brief sobre los builds
node scripts/scale-test.mjs	Prueba de escala (flujo 6): genera ~1200 páginas y mide tiempo y RAM

Poné DOCS_FASTER=1 para usar el bundler Rspack de Docusaurus Faster: en la prueba de escala bajó el build de 307 s a 84 s.

Cómo se escribe un artículo

Frontmatter mínimo:

---
title: Facturas de cliente        # obligatorio
type: concepto                    # concepto | referencia | tarea | troubleshooting | guia | indice
versions: ["18", "19"]            # obligatorio en manual/ y guias/; prohibido en relacion/
audience: publico                 # publico (default) | interno — el artículo entero
modules: ["account", "l10n_ar"]   # docs-as-data (task 71329): viaja tal cual al build
---

Dos bloques marcados, que Docusaurus nunca ve porque el preprocesador los resuelve antes:

:::interno
Solo se emite en el build interno. En el público no está: ni en el HTML, ni
en el JS, ni en el índice de búsqueda.
:::

:::solo-version 19
Se emite únicamente en la versión 19.
:::

Reglas de contenido que la PoC dejó en evidencia:

• Los links dentro del árbol versionado van relativos al archivo y con extensión (./facturacion/facturas-de-cliente.md). Una ruta absoluta /19/manual/... apunta siempre a la misma versión y rompe el árbol único.
• Un artículo reescrito de raíz para otra versión es un archivo hermano nombre.vNN.md con versions: disjunto y el mismo slug.

Estructura

content/                    ÁRBOL FUENTE — lo único que se edita
  manual/                     versionado
  guias/                      versionado
  relacion/                   cross-version (sin `versions:`)
  **/_categoria.json          label y orden de cada carpeta en la nav
poc.config.json             versiones, audiencias, tipos válidos
tools/build.mjs             el preprocesador del ADR 0004
scripts/gen-synthetic.mjs   generador de contenido para la prueba de escala
scripts/scale-test.mjs      flujo 6 — tiempo y RAM
scripts/verificar.mjs       criterios de aceptación del brief, verificados sobre el HTML
site/                       proyecto Docusaurus (consume el árbol generado)
.github/workflows/docs.yml  lint + dos builds + verificación en cada PR

Sobre el contenido

Los ~17 artículos salen de la documentación real de OBA 18/19 (vía el RAG del manual), reescritos con la anatomía de estructura-contenido.md. No usan la skill adhoc-doc-standards v1 porque todavía no existe — la 71328 es de coa y estaba abierta al momento de armar esto. Cuando exista, los artículos hay que reescribirlos con ella: son el test de la skill, no una fuente paralela.