addons-cm/docs/OCA_DOCUMENTATION.md

# OCA Documentation Structure

## Overview

Los addons custom del proyecto ahora siguen los **estándares OCA** para documentación, usando el directorio `/readme` con fragmentos `.rst` que se ensamblan automáticamente para generar el README final.

## Estructura de Directorios

Cada addon tiene la siguiente estructura de documentación:

```
addon_name/
├── __manifest__.py          # Manifest con autor "Criptomart"
├── README.rst               # README automático generado (OCA standard)
├── README_DEV.md            # README para desarrolladores (ex-README.md)
├── readme/                  # Fragmentos para generar README.rst
│   ├── DESCRIPTION.rst      # Descripción del módulo
│   ├── INSTALL.rst          # Instrucciones de instalación
│   ├── CONFIGURE.rst        # Configuración
│   ├── USAGE.rst            # Guía de uso
│   ├── CONTRIBUTORS.rst     # Lista de contribuidores
│   └── CREDITS.rst          # Créditos y financiadores
└── static/
    └── description/
        └── icon.png         # Logo de CriptoMart (256x256 px)
```

## Addons Actualizados

Los siguientes addons custom han sido actualizados con la estructura OCA:

1. **website_sale_aplicoop** - Sistema de pedidos grupales (eskaera)
2. **product_sale_price_from_pricelist** - Auto-cálculo de precios de venta
3. **product_pricelist_total_margin** - Márgenes aditivos en pricelists
4. **product_price_category_supplier** - Categorías de precio por proveedor
5. **account_invoice_triple_discount_readonly** - Fix para triple descuento

## Créditos en Documentación

Todos los addons incluyen correctamente:

- **Autor**: Criptomart (en `__manifest__.py` y `README.rst`)
- **Financiador**: Elika Bilbo (en `readme/CREDITS.rst`)

## Logo de CriptoMart

Todos los addons custom deben incluir el logo de CriptoMart en:

```
addon_name/static/description/icon.png
```

**Especificaciones del logo:**

- Formato: PNG
- Tamaño recomendado: 256x256 px (o 128x128 px)
- Fondo: Transparente o blanco
- Ratio: Cuadrado (1:1)

**Para instalar el logo:**

Ver instrucciones detalladas en [docs/LOGO_INSTRUCTIONS.md](LOGO_INSTRUCTIONS.md).

Script rápido:
```bash
# 1. Guardar logo adjunto como /tmp/criptomart_logo.png
# 2. Ejecutar:
bash docs/install_logo.sh
```

El logo aparecerá en la lista de Apps de Odoo y en las páginas de información del módulo.

## Generación Automática del README

Para generar automáticamente el `README.rst` desde los fragmentos, usa la herramienta OCA:

```bash
# Instalar oca-gen-addon-readme
pip install oca-gen-addon-readme

# Generar README para un addon
cd addon_name/
oca-gen-addon-readme

# O generar para todos los addons
for addon in website_sale_aplicoop product_*; do
    cd "$addon" && oca-gen-addon-readme && cd ..
done
```

## Fragmentos del Directorio readme/

### DESCRIPTION.rst (Obligatorio)

Descripción breve del módulo y sus funcionalidades principales. Se muestra al inicio del README.

### INSTALL.rst (Opcional)

Instrucciones específicas de instalación si el módulo requiere pasos adicionales al proceso estándar.

### CONFIGURE.rst (Opcional)

Pasos de configuración necesarios después de instalar el módulo.

### USAGE.rst (Obligatorio)

Guía de uso del módulo con ejemplos prácticos y flujos de trabajo.

### CONTRIBUTORS.rst (Obligatorio)

Lista de personas y organizaciones que han contribuido al desarrollo.

Formato:
```rst
* `Criptomart <https://criptomart.net>`_:

  * Role/contribution description
```

### CREDITS.rst (Obligatorio)

Información sobre autores, financiadores y otros créditos.

Formato estándar:
```rst
**Authors:**

* Criptomart

**Funding:**

* Elika Bilbo

**Other credits:**

Additional information about the module development.
```

## README_DEV.md

Los archivos `README.md` originales han sido renombrados a `README_DEV.md` para mantenerlos como referencia de desarrollo sin que interfieran con la documentación oficial OCA.

Estos archivos contienen:
- Información técnica detallada
- Notas de implementación
- Ejemplos de código
- Detalles de arquitectura

## Referencias

- [OCA README Structure](https://odoo-community.org/readme-structure)
- [OCA README Guidelines](https://odoo-community.org/read-me-guidelines)
- [oca-gen-addon-readme Tool](https://pypi.org/project/oca-gen-addon-readme/)

## Mantenimiento

Al actualizar un addon:

1. Actualiza los fragmentos en `readme/` según corresponda
2. NO edites directamente `README.rst` (se sobrescribirá)
3. Usa `README_DEV.md` para notas técnicas de desarrollo
4. Regenera `README.rst` con `oca-gen-addon-readme`
5. Actualiza `__manifest__.py` version cuando hagas cambios significativos

## Validación

Para verificar que la documentación cumple con los estándares OCA:

```bash
# Instalar herramientas de validación OCA
pip install pre-commit

# Ejecutar validación
pre-commit run --all-files
```