Modifiche automatiche al codice

doQumentation applica automaticamente un piccolo numero di modifiche ai contenuti upstream dei tutorial e delle guide di Qiskit per garantire un'esperienza interattiva fluida. Questa pagina documenta ogni modifica in modo che tu possa capire esattamente cosa è cambiato rispetto alla documentazione originale di IBM Quantum.

Copie dei notebook (Apri in Colab / Binder / Code Engine)

Quando fai clic su Apri in Colab, Apri in JupyterLab o Apri in Code Engine, ricevi una copia del notebook originale con queste aggiunte:

1. Cella di avviso di configurazione (markdown)

Una cella blockquote viene inserita in cima, spiegando che doQumentation ha aggiunto una cella di configurazione automatica. Contiene un link che rimanda a questa pagina.

2. Cella dei prerequisiti (codice)

Una cella di codice viene inserita dopo l'avviso e:

• Installa i pacchetti richiesti (qiskit, qiskit-aer, qiskit-ibm-runtime, pylatexenc, più eventuali pacchetti specifici del tutorial rilevati tramite scansione degli import). L'installazione viene saltata se i pacchetti sono già presenti (ad es. su Binder o Code Engine dove sono pre-installati).

• Fornisce un template commentato per le credenziali di IBM Quantum, in modo che gli utenti che vogliono eseguire su hardware reale possano decommentare e inserire la propria chiave API.

Su Google Colab, questa cella viene eseguita automaticamente all'apertura del notebook tramite il flag di metadati cell_execution_strategy: setup.

3. Riscrittura dei percorsi delle immagini

I percorsi relativi delle immagini (/docs/images/..., /learning/images/...) vengono riscritti per funzionare correttamente in ambienti notebook standalone.

Pagine MDX (rendering nel browser)

I tutorial visualizzati su questo sito vengono convertiti dai notebook .ipynb upstream o da file .mdx. Vengono applicate le seguenti trasformazioni:

• Righe pip install vengono aggiunte ai blocchi di codice Python che importano pacchetti di terze parti, abilitando l'esecuzione con un clic tramite thebelab.

• Sezione IBM Tutorial Survey: viene aggiunta una nota che chiarisce che il sondaggio appartiene a IBM Quantum e che rimanda alle GitHub Issues di doQumentation per feedback specifici al sito.

• Widget di feedback: un widget "È stato utile?" viene aggiunto in fondo a ogni tutorial, tracciato tramite Umami analytics rispettosa della privacy.

• Correzioni sintassi MDX: le parentesi graffe, la gerarchia dei titoli e i problemi di compatibilità JSX vengono corretti automaticamente per il rendering con Docusaurus.

• OpenInLabBanner: un banner interattivo viene iniettato sotto il titolo con pulsanti per aprire il notebook in Colab, Binder o Code Engine.

Cosa NON viene modificato

• Il contenuto del tutorial stesso (spiegazioni, logica del codice, output) non viene mai alterato.

• L'attribuzione degli autori originali è preservata tramite il frontmatter e il file NOTICE (licenze Apache 2.0 / CC BY-SA 4.0).

• Nessun codice di telemetria o tracciamento viene iniettato nei notebook. Analytics (Umami) viene eseguito solo sul sito web di doQumentation, non nei notebook esportati.

Codice sorgente

Tutte le trasformazioni sono implementate in scripts/sync-content.py.