Automatyczne modyfikacje kodu

doQumentation automatycznie wprowadza niewielką liczbę modyfikacji w treściach samouczków i przewodników Qiskit pochodzących z upstream, aby zapewnić płynne, interaktywne doświadczenie. Ta strona dokumentuje każdą modyfikację, dzięki czemu możesz dokładnie zrozumieć, co zmieniło się w porównaniu z oryginalną dokumentacją IBM Quantum.

Kopie notebooków (Otwórz w Colab / Binder / Code Engine)

Gdy klikniesz Open in Colab, Open in JupyterLab lub Open in Code Engine, otrzymujesz kopię oryginalnego notebooka z następującymi uzupełnieniami:

1. Komórka z informacją o konfiguracji (markdown)

Na samej górze wstawiana jest komórka typu blockquote, wyjaśniająca, że doQumentation dodało automatyczną komórkę konfiguracyjną. Zawiera link prowadzący z powrotem do tej strony.

2. Komórka wstępna (kod)

Po komórce z informacją wstawiana jest komórka kodu, która:

• Instaluje wymagane pakiety (qiskit, qiskit-aer, qiskit-ibm-runtime, pylatexenc, a także wszelkie pakiety specyficzne dla danego samouczka, wykryte przez skanowanie importów). Instalacja jest pomijana, jeśli pakiety są już dostępne (np. w Binder lub Code Engine, gdzie są wstępnie zainstalowane).
• Udostępnia zakomentowany szablon poświadczeń dla IBM Quantum, dzięki czemu użytkownicy, którzy chcą uruchomić kod na prawdziwym sprzęcie, mogą odkomentować i uzupełnić swój klucz API.

W Google Colab ta komórka uruchamia się automatycznie po otwarciu notebooka, za pomocą flagi metadanych cell_execution_strategy: setup.

3. Przepisywanie ścieżek do obrazów

Względne ścieżki do obrazów (/docs/images/..., /learning/images/...) są przepisywane tak, aby działały poprawnie w samodzielnych środowiskach notebooków.

Strony MDX (renderowanie w przeglądarce)

Samouczki wyświetlane na tej stronie są konwertowane z notebooków .ipynb lub plików .mdx pochodzących z upstream. Stosowane są następujące przekształcenia:

• Linie pip install są dodawane do bloków kodu Python importujących pakiety zewnętrzne, co umożliwia wykonanie jednym kliknięciem za pośrednictwem thebelab.
• Sekcja IBM Tutorial Survey: Dołączana jest notatka wyjaśniająca, że ankieta należy do IBM Quantum, oraz link do GitHub Issues doQumentation umożliwiający przesyłanie opinii dotyczących tej strony.
• Widget z opinią: Na dole każdego samouczka dołączany jest widget „Was this helpful?", śledzony przez przyjazną prywatności analitykę Umami.
• Poprawki składni MDX: Klamry, hierarchia nagłówków i problemy ze zgodnością z JSX są automatycznie korygowane na potrzeby renderowania w Docusaurus.
• OpenInLabBanner: Poniżej tytułu wstrzykiwany jest interaktywny baner z przyciskami umożliwiającymi otwarcie notebooka w Colab, Binder lub Code Engine.

Co NIE jest modyfikowane

• Sama treść samouczka (wyjaśnienia, logika kodu, wyniki) nigdy nie jest zmieniana.
• Atrybucja oryginalnych autorów jest zachowywana przez frontmatter i plik NOTICE (licencje Apache 2.0 / CC BY-SA 4.0).
• Żaden kod telemetryczny ani śledzący nie jest wstrzykiwany do notebooków. Analityka (Umami) działa wyłącznie na stronie doQumentation, a nie w eksportowanych notebookach.

Kod źródłowy

Wszystkie przekształcenia są zaimplementowane w scripts/sync-content.py.