Автоматичні модифікації коду

doQumentation автоматично застосовує невелику кількість модифікацій до вихідного вмісту підручників і посібників Qiskit, щоб забезпечити зручний інтерактивний досвід. На цій сторінці задокументовано кожну модифікацію, щоб ти міг точно зрозуміти, що змінилося порівняно з оригінальною документацією IBM Quantum.

Копії ноутбуків (Відкрити у Colab / Binder / Code Engine)

Коли ти натискаєш Відкрити у Colab, Відкрити у JupyterLab або Відкрити у Code Engine, ти отримуєш копію оригінального ноутбука з такими доповненнями:

1. Клітинка з повідомленням про налаштування (markdown)

На самому початку вставляється клітинка-цитата, яка пояснює, що doQumentation додав автоматичну клітинку налаштування. Вона містить посилання на цю сторінку.

2. Клітинка з передумовами (код)

Після повідомлення вставляється клітинка коду, яка:

• Встановлює необхідні пакети (qiskit, qiskit-aer, qiskit-ibm-runtime, pylatexenc, а також будь-які специфічні для підручника пакети, виявлені через сканування імпортів). Встановлення пропускається, якщо пакети вже присутні (наприклад, у Binder або Code Engine, де вони попередньо встановлені).

• Надає закоментований шаблон облікових даних для IBM Quantum, щоб користувачі, які хочуть запустити на реальному обладнанні, могли розкоментувати та заповнити свій API-ключ.

У Google Colab ця клітинка автоматично виконується під час відкриття ноутбука завдяки прапорцю метаданих cell_execution_strategy: setup.

3. Переписування шляхів до зображень

Відносні шляхи до зображень (/docs/images/..., /learning/images/...) переписуються для коректної роботи у самостійних середовищах виконання ноутбуків.

MDX-сторінки (рендеринг у браузері)

Підручники, які відображаються на цьому сайті, конвертуються з вихідних .ipynb-ноутбуків або .mdx-файлів. Застосовуються такі перетворення:

• Рядки pip install додаються до блоків коду Python, які імпортують сторонні пакети, що дозволяє виконання в один клік через thebelab.

• Розділ опитування підручника IBM: Додається примітка, яка уточнює, що опитування належить IBM Quantum та містить посилання на GitHub Issues проєкту doQumentation для зворотного зв'язку щодо сайту.

• Віджет зворотного зв'язку: Внизу кожного підручника додається віджет «Чи було це корисно?», відстежуваний через Umami — аналітику, що поважає конфіденційність.

• Виправлення синтаксису MDX: Фігурні дужки, ієрархія заголовків та проблеми сумісності JSX автоматично виправляються для рендерингу в Docusaurus.

• OpenInLabBanner: Нижче заголовка вставляється інтерактивний банер із кнопками для відкриття ноутбука у Colab, Binder або Code Engine.

Що НЕ змінюється

• Сам вміст підручника (пояснення, логіка коду, результати) ніколи не змінюється.

• Атрибуція оригінальних авторів зберігається через frontmatter та файл NOTICE (ліцензії Apache 2.0 / CC BY-SA 4.0).

• Жодного коду телеметрії чи відстеження не вставляється в ноутбуки. Аналітика (Umami) працює лише на сайті doQumentation, а не в експортованих ноутбуках.

Вихідний код

Усі перетворення реалізовані у scripts/sync-content.py.