Modificaciones Automáticas de Código

doQumentation aplica automáticamente un pequeño número de modificaciones al contenido de tutoriales y guías de Qiskit para garantizar una experiencia interactiva y fluida. Esta página documenta cada modificación para que puedas entender exactamente qué cambió en comparación con la documentación original de IBM Quantum.

Copias de notebooks (Abrir en Colab / Binder / Code Engine)

Cuando haces clic en Open in Colab, Open in JupyterLab o Open in Code Engine, recibes una copia del notebook original con estas adiciones:

1. Celda de aviso de configuración (markdown)

Se inserta una celda de cita en bloque al principio del notebook que explica que doQumentation añadió una celda de configuración automática. Incluye un enlace de vuelta a esta página.

2. Celda de requisitos previos (código)

Se inserta una celda de código después del aviso que:

• Instala los paquetes necesarios (qiskit, qiskit-aer, qiskit-ibm-runtime, pylatexenc, además de cualquier paquete específico del tutorial detectado mediante análisis de importaciones). La instalación se omite si los paquetes ya están presentes (por ejemplo, en Binder o Code Engine donde vienen preinstalados).

• Proporciona una plantilla de credenciales comentada para IBM Quantum, para que los usuarios que quieran ejecutar en hardware real puedan descomentar y completar su clave API.

En Google Colab, esta celda se ejecuta automáticamente al abrir el notebook mediante el indicador de metadatos cell_execution_strategy: setup.

3. Reescritura de rutas de imágenes

Las rutas de imágenes relativas (/docs/images/..., /learning/images/...) se reescriben para funcionar correctamente en entornos de notebook independientes.

Páginas MDX (renderizado en el navegador)

Los tutoriales que se muestran en este sitio web se convierten desde notebooks .ipynb o archivos .mdx originales. Se aplican las siguientes transformaciones:

• Líneas pip install se añaden a los bloques de código Python que importan paquetes de terceros, permitiendo la ejecución con un clic mediante thebelab.

• Sección de encuesta de tutoriales de IBM: Se añade una nota que aclara que la encuesta pertenece a IBM Quantum y que enlaza a los Issues de GitHub de doQumentation para comentarios específicos del sitio.

• Widget de retroalimentación: Se añade un widget "¿Te fue útil?" al final de cada tutorial, cuyas métricas se recogen con Umami, una herramienta de analítica respetuosa con la privacidad.

• Correcciones de sintaxis MDX: Las llaves, la jerarquía de encabezados y los problemas de compatibilidad con JSX se corrigen automáticamente para el renderizado con Docusaurus.

• OpenInLabBanner: Se inyecta un banner interactivo debajo del título con botones para abrir el notebook en Colab, Binder o Code Engine.

Qué NO se modifica

• El contenido del tutorial en sí (explicaciones, lógica del código, resultados) nunca se altera.

• La atribución al autor original se conserva mediante el frontmatter y el archivo NOTICE (licencias Apache 2.0 / CC BY-SA 4.0).

• No se inyecta ningún código de telemetría o seguimiento en los notebooks. El análisis (Umami) solo se ejecuta en el sitio web de doQumentation, no en los notebooks exportados.

Código fuente

Todas las transformaciones están implementadas en scripts/sync-content.py.