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.

Script rápido:

# 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:

# 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:

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

  * Role/contribution description

CREDITS.rst (Obligatorio)

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

Formato estándar:

**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
• OCA README Guidelines
• oca-gen-addon-readme Tool

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:

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

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