How somosnlp/the-annotated-transformer works
Para dibujar un diagrama de arquitectura claro y ajustado a este proyecto (“The Annotated Transformer” en español), sigue estos pasos:
Identificar el tipo de proyecto y su propósito
• Este repositorio es un proyecto educativo/documental: contiene notebooks interactivos y módulos Python que explican e implementan cada pieza de la arquitectura Transformer (Positional Encoding, Multi-Head Attention, etc.), más una documentación generada con Sphinx y alojada en Read the Docs.
• No es una aplicación de usuario final ni un microservicio, sino un “pipeline” de generación de contenido técnico.
Analizar la estructura lógica (basado en el README)
• Código fuente: directorio donde viven los módulos Python con las implementaciones (p. ej. src/ o transformers/)
• Notebooks: varios .ipynb, uno por pieza (positional_encoding.ipynb, multihead_attention.ipynb…)
• Documentación estática: configuración de Sphinx (conf.py, docs/), archivos rst/markdown para cada sección
• Integración continua: CI (GitHub Actions o similar) que ejecuta notebooks y construye la doc
• Hosting: Read the Docs publica la documentación finalizada
Componentes principales a representar
A. Repositorio GitHub
B. Contribuidores / Issues / Pull Requests
C. Módulos Python de implementación (p. ej. transformers/*.py)
D. Jupyter Notebooks interactivos
E. Sphinx (procesador de documentación)
F. Pipeline CI/CD (GitHub Actions → ejecución de notebooks + build de Sphinx)
G. Read the Docs (hosting de la web)
H. Dependencias externas: PyTorch o TensorFlow, librerías Python de Jupyter y Sphinx
Relaciones e interacciones
• Los contribuyentes abren Issues y PRs en GitHub
• Al “merge” se dispara el pipeline CI/CD
• CI/CD:
• Ejecuta tests unitarios de los módulos Python
• Ejecuta/convierte los notebooks a HTML (opcional)
• Lanza el build de la documentación con Sphinx
• Sphinx consume:
• Código Python (autodoc)
• Notebooks (nbsphinx o similar)
• Resultado → artefacto HTML
• Read the Docs obtiene el artefacto y lo publica en la URL pública
• Usuario final (lector) accede vía navegador
Patrones y principios arquitecturales
• Pipeline de integración continua (CI/CD)
• Separación de contenidos:
• “Code as documentation”: módulos Python documentados con docstrings
• Notebooks para explicación interactiva
• Infraestructura como código para configuración de build y hosting
Tecnologías y librerías clave
• Python 3.x
• PyTorch y/o TensorFlow
• Jupyter / nbsphinx
• Sphinx + extensiones (autodoc, napoleon, readthedocs theme)
• GitHub Actions (o GitLab CI)
• Read the Docs
Guía para el diagrama final
• Usa cajas rectangulares para cada componente (GitHub, módulos, notebooks, Sphinx, CI, Read the Docs, usuario)
• Flechas con etiquetas que indiquen el flujo (“push → CI/CD”, “CI/CD → build docs”, “build docs → Read the Docs”, “usuario → lee docs”)
• Colores o formas diferentes para:
• Componentes de desarrollo (GitHub, CI)
• Artefactos de contenido (módulos Python, notebooks, HTML generado)
• Infraestructura de hosting (Read the Docs)
• Roles humanos (contribuidores, usuarios)
Con este diagrama tendrás una vista clara del flujo de contribución, generación de documentación y consumo final, capturando todos los elementos esenciales sin dispersarte en detalles innecesarios. ¡Listo para diseñar el diagrama!