Saltar a contenido

Referencia docs.yaml

.raise/docs.yaml es el archivo de configuración del adaptador de documentación de RaiSE. Le indica a rai docs publish dónde enviar los artifacts de documentación y cómo enrutar cada tipo de artifact a la página padre correcta.

¿Actualizando desde 2.x?

En RaiSE 3.0, confluence.yaml fue reemplazado por docs.yaml. El formato es similar pero usa default_target: y targets: en lugar de default_instance: e instances:. Ver Auto-migración más abajo — no necesitas migrar manualmente.

Para el procedimiento completo de actualización, consulta la Guía de Migración.

Ubicación del Archivo

.raise/docs.yaml

Este archivo vive en la raíz del directorio .raise/ de tu proyecto y se versiona en git (compartido en el equipo). Describe a qué conectarse — las credenciales (tokens API, usernames) se mantienen en variables de entorno.

Campos de Nivel Superior

Campo Tipo Por defecto Descripción
default_target string "default" Qué target usar cuando no se especifica --target
targets mapa requerido Targets de documentación con nombre

Campos de Target (targets.<nombre>)

Cada entrada bajo targets: es un target de documentación con nombre. Actualmente solo se soporta type: confluence.

Target de Confluence

Campo Tipo Requerido Descripción
type "confluence" sí Discriminador de tipo de adaptador
url string sí URL base de Confluence (p.ej. https://yoursite.atlassian.net/wiki)
space_key string sí Clave de espacio Confluence por defecto (p.ej. TEAM)
instance_name string no Identificador de instancia para resolución de tokens. Por defecto: "default"
username string no Email de cuenta Atlassian — generalmente omitido y leído desde la variable de entorno CONFLUENCE_USERNAME
home_page_id string no ID de la página principal del espacio — usado como ancestro de reserva cuando una entrada de enrutamiento no tiene página padre. Proporcionar como string entre comillas ("123456")
routing mapa no Tipo de artifact → configuración de enrutamiento. Mapa vacío {} es válido (usa home_page_id como reserva)

Campos de Enrutamiento (targets.<nombre>.routing.<tipo_artifact>)

Cada entrada bajo routing: mapea un tipo de artifact (p.ej. adr, session-diary) a una página padre de Confluence.

Campo Tipo Requerido Descripción
parent_title string sí Título de la página de Confluence bajo la que publicar
labels lista de strings no Etiquetas aplicadas a la página al publicar
local_dir string no Directorio base local para rai docs write (fallback de sistema de archivos)
naming "slug" o "dated" no Convención de nombres de archivo. slug → {slug}.md, dated → {YYYY-MM-DD}-{slug}.md. Por defecto: "slug"

Ejemplo Mínimo

Un target de Confluence, sin enrutamiento configurado. Usa home_page_id para que rai docs publish tenga una página padre de reserva.

default_target: default
targets:
  default:
    type: confluence
    url: https://myteam.atlassian.net/wiki
    space_key: TEAM
    instance_name: default
    home_page_id: "123456789"
    routing: {}

Ejemplo Completo

Dos targets con configuración de enrutamiento — un espacio principal y uno de staging.

default_target: main
targets:
  main:
    type: confluence
    url: https://myteam.atlassian.net/wiki
    space_key: TEAM
    instance_name: main
    home_page_id: "123456789"
    routing:
      adr:
        parent_title: Arquitectura
        labels: [adr, arquitectura]
        local_dir: dev/decisions
        naming: slug
      session-diary:
        parent_title: Diarios de Sesión
        labels: [session-diary]
        local_dir: work/sessions
        naming: dated
      epic-docs:
        parent_title: Docs de Desarrollador
        labels: [epic-docs]
        local_dir: work/epics
        naming: slug
      roadmap:
        parent_title: Producto
        labels: [roadmap]
        local_dir: governance
        naming: slug
  staging:
    type: confluence
    url: https://myteam.atlassian.net/wiki
    space_key: STAGING
    instance_name: main
    routing: {}

Usar Múltiples Targets

El flag --target en rai docs publish reemplaza default_target para un único comando:

# Publicar al target por defecto (main)
rai docs publish adr --title "ADR-045"

# Reemplazar al target staging
rai docs publish adr --title "ADR-045" --target staging

Auto-migración

Si tu proyecto todavía tiene .raise/confluence.yaml, RaiSE lo migra automáticamente en la primera llamada a rai docs write:

  1. RaiSE lee confluence.yaml
  2. Transforma default_instance: → default_target:, instances: → targets:, agrega type: confluence a cada target
  3. Escribe el nuevo docs.yaml en .raise/docs.yaml
  4. Imprime: [rai] Migrated .raise/confluence.yaml → .raise/docs.yaml

Tras la migración, haz commit del nuevo archivo:

git add .raise/docs.yaml
git commit -m "chore: migrate confluence.yaml to docs.yaml (RaiSE 3.0)"

El confluence.yaml antiguo todavía se lee como fallback hasta que lo elimines. Elimínalo tras confirmar que docs.yaml funciona:

git rm .raise/confluence.yaml

Variables de Entorno

Los tokens API y usernames nunca se almacenan en docs.yaml. Establécelos en tu shell:

export CONFLUENCE_API_TOKEN="your-token"
export CONFLUENCE_USERNAME="[email protected]"

Agrégalos a .bashrc o .zshrc para persistencia, o usa un archivo .env con direnv.

Ver También