Automatické úpravy kódu

doQumentation automaticky provádí několik drobných úprav obsahu tutoriálů a průvodců Qiskitu z upstream zdrojů, aby zajistila plynulý a interaktivní zážitek. Tato stránka dokumentuje každou úpravu, abys přesně věděl/a, co se změnilo oproti původní dokumentaci IBM Quantum.

Kopie notebooků (Otevřít v Colabu / Binderu / Code Engine)

Když klikneš na Otevřít v Colabu, Otevřít v JupyterLabu nebo Otevřít v Code Engine, obdržíš kopii původního notebooku s těmito doplňky:

1. Buňka s upozorněním na nastavení (markdown)

Na úplný začátek je vložena buňka s blokovým citátem, která vysvětluje, že doQumentation přidala automatickou nastavovací buňku. Odkazuje zpět na tuto stránku.

2. Buňka s předpoklady (kód)

Po upozornění je vložena kódová buňka, která:

• Instaluje potřebné balíčky (qiskit, qiskit-aer, qiskit-ibm-runtime, pylatexenc a veškeré balíčky specifické pro daný tutoriál zjištěné skenováním importů). Instalace je přeskočena, pokud jsou balíčky již přítomny (např. v Binderu nebo Code Engine, kde jsou předinstalovány).

• Poskytuje zakomentovanou šablonu přihlašovacích údajů pro IBM Quantum, aby uživatelé, kteří chtějí spouštět kód na skutečném hardwaru, mohli odkomentovat šablonu a vyplnit svůj API klíč.

V Google Colabu se tato buňka automaticky spustí při otevření notebooku pomocí příznaku metadat cell_execution_strategy: setup.

3. Přepisy cest k obrázkům

Relativní cesty k obrázkům (/docs/images/..., /learning/images/...) jsou přepsány tak, aby správně fungovaly v samostatných prostředích notebooků.

Stránky MDX (vykreslování v prohlížeči)

Tutoriály zobrazené na tomto webu jsou převedeny z upstream .ipynb notebooků nebo .mdx souborů. Jsou aplikovány následující transformace:

• Řádky pip install jsou přidány do bloků kódu v Pythonu, které importují balíčky třetích stran, což umožňuje spuštění jedním kliknutím prostřednictvím thebelabu.

• Sekce IBM Tutorial Survey: Je přidána poznámka upřesňující, že průzkum patří IBM Quantum, s odkazem na GitHub Issues doQumentation pro zpětnou vazbu specifickou pro tento web.

• Widget zpětné vazby: Na konec každého tutoriálu je přidán widget „Bylo to užitečné?", sledovaný prostřednictvím analytiky Umami šetrné k soukromí.

• Opravy syntaxe MDX: Složené závorky, hierarchie nadpisů a problémy s kompatibilitou JSX jsou automaticky opraveny pro vykreslování v Docusaurusu.

• OpenInLabBanner: Pod nadpis je vložen interaktivní banner s tlačítky pro otevření notebooku v Colabu, Binderu nebo Code Engine.

Co se NEMĚNÍ

• Samotný obsah tutoriálu (vysvětlení, logika kódu, výstupy) není nikdy měněn.

• Atribuce původních autorů je zachována prostřednictvím frontmatter a souboru NOTICE (licence Apache 2.0 / CC BY-SA 4.0).

• Do notebooků není vkládán žádný telemetrický ani sledovací kód. Analytika (Umami) běží pouze na webu doQumentation, nikoliv v exportovaných noteboocích.

Zdrojový kód

Všechny transformace jsou implementovány v scripts/sync-content.py.