@imolko/ultra-reporter

¿Cómo usar ultra-reporter version 2?

1. Instale el paquete @imolko/ultra-reporter en su ultima version:

npm install @imolko/ultra-reporter

2. Instale el paquete better-docs en su repositorio:

Este paquete es una peer-dependency de @imolko/ultra-reporter y es necesario para generar la documentacion de los artefactos.

npm install better-docs --save-dev --legacy-peer-deps

3. Instale el paquete jest-ctrf-json-reporter en su ultima version:

npm i jest-ctrf-json-reporter --save-dev

4. Agregue la siguiente configuracion al jest en su archivo jest.config.js:

module.exports = {
  ...
  reporters: [
    "default",
    [
      'jest-ctrf-json-reporter',
      {
        outputDir: '.',
        outputFile: 'ctrf.json',
      }
    ],
  ],
  ...
};

Ejecute los test para generar el archivo ctrf.json:

npm run test

5. Corra el comando para crear el proyecto de documentacion

Desde el root del repositorio, ejecute el siguiente comando:

npx @imolko/ultra-reporter init -d -p documentation

• -d indica que debe mostrar todos los mensajes de debug.
• -p indica el nombre del proyecto de documentacion (el nombre de la carpeta donde se generara la documentacion).

6. Configure el archivo documentation/ultra-reporter.config.json

{
  "targets": [
    {
      "type": "domain", // Indica el tipo de target (domain/use-cases)
      "packageRoot": "./domain", // Indica el root del paquete tarjet
      "domainSrc": "./domain/src", // Indica el path de la carpeta dond estan todos los artefactos
      "contextName": "sentinel", // Indica el nombre del contexto (valor domain en el @RegisterValueObject del artefacto)
      "testsResultFile": "./domain/ctrf.json", // Indica el path del archivo de resultados de los test
      "docusaurus": {
        // Configuracion docusaurus para el tab domain y aggregates
        "domain": {
          "name": "sentinel-domain", // Indica el nombre del tab en docusaurus con contendra la documentacion de los artefactos: Entities y ValueObjects
          "config": {
            // Configuracion docusaurus para el tab
            "label": "Sentinel Domain Artifacts",
            "position": 2,
            "link": {
              "type": "generated-index",
              "description": "Todos los artefactos del dominio"
            }
          }
        },
        "aggregates": {
          "name": "sentinel-aggregates", // Indica el nombre del tab en docusaurus con contendra la documentacion de los artefactos: Agregates
          "config": {
            // Configuracion docusaurus para el tab (ver documentacion https://docusaurus.io/docs/sidebar/items#sidebar-item-category)
            "label": "Sentinel Aggregates",
            "position": 1,
            "link": {
              "type": "generated-index",
              "description": "Aggregates del dominio"
            }
          }
        }
      }
    },
    {
      "type": "use-cases", // Indica el tipo de target (domain/use-cases)
      "title": "Sentinel Use Cases", // Indica el titulo del tab en docusaurus con contendra la documentacion de los casos de uso
      "packageRoot": "./features", // Indica el root del paquete tarjet
      "useCasesSrc": "./features/src", // Indica el path de la carpeta dond estan todos los casos de uso
      "testsResultFile": "./features/ctrf.json", // Indica el path del archivo de resultados de los test
      "docusaurus": {
        // Configuracion docusaurus para el tab
        "useCases": {
          // Configuracion docusaurus para el tab (ver documentacion https://docusaurus.io/docs/sidebar/items#sidebar-item-category)
          "name": "sentinel-use-cases",
          "config": {
            "label": "Sentinel Use Cases",
            "position": 3,
            "link": {
              "type": "generated-index",
              "description": "Todos los casos de uso"
            }
          }
        }
      }
    }
  ]
}

7. Corra los test de jest

Corra los test de jest para generar el archivo ctrf.json en cad uno de los paquetes target

npm run test

ó

npx jest

8. Corra el comando para generar la documentacion:

Desde el root del repositorio, ejecute el siguiente comando:

npx @imolko/ultra-reporter generate-documentation -d -p documentation

• -d indica que debe mostrar todos los mensajes de debug.
• -p indica el nombre del proyecto de documentacion (el nombre de la carpeta donde se generara la documentacion).

¿Cómo correr el servidor web de documentación?

1. Estando dentro de la carpeta documentation instale las dependencias:

npm install

2. Corra el servidor de documentacion:

npm run start

Consideraciones

1. La documentacion relacionada al paquete debe estar en un archivo llamado context-intro.md en la carpeta src.

2. Este generador asume que la estructura de los archivos en la capeta carpetta de cada artefacto hace uso del paquete @imolko/ultra-ddd y por tanto tiene una estructura como la siguiente:

domain
├── src
│   ├── Artifact1
│   │   ├── attachments.md
│   │   ├── conditions.ts
│   │   ├── definition.ts
│   │   ├── definition.yaml
│   │   ├── entity.spec.ts
│   │   ├── entity.ts
│   │   ├── index.ts
│   │   ├── payload.ts
│   │   ├── primitive.ts
│   │   ├── props.ts
│   └── Artifact2
│   │   ├── ...
└── context-intro.md

Los archivos attachments.md y definition.yaml contiene parte importante de la documentacion de los artefactos, por lo que es importante que esten presentes en la estructura de los archivos y este bien documentados.

3. En la carpeta documentation se generan los archivos relacionados con la documentacion de los artefactos y una introducccion al contexto.

4. Dentro de documentation hay archivos que deben ser editados para ajustarlos a cada contexto, como:

• /documentation/docusaurus.config.ts

5. Dentro de documentation se pueden generar paginas y blogs para documentar de forma manual otros aspectos del contexto. Vea Docusaurus