Modificações automáticas de código

A doQumentation aplica automaticamente um pequeno número de modificações ao conteúdo upstream de tutoriais e guias do Qiskit para garantir uma experiência interativa fluida. Esta página documenta cada modificação para que você possa entender exatamente o que mudou em comparação com a documentação original do IBM Quantum.

Cópias de notebooks (Open in Colab / Binder / Code Engine)

Quando você clica em Open in Colab, Open in JupyterLab ou Open in Code Engine, recebe uma cópia do notebook original com estes acréscimos:

1. Célula de aviso de configuração (markdown)

Uma célula de blockquote é inserida no topo, explicando que a doQumentation adicionou uma célula de configuração automática. Ela contém um link de volta para esta página.

2. Célula de pré-requisitos (código)

Uma célula de código é inserida após o aviso, que:

• Instala os pacotes necessários (qiskit, qiskit-aer, qiskit-ibm-runtime, pylatexenc, além de quaisquer pacotes específicos do tutorial detectados via varredura de imports). A instalação é ignorada se os pacotes já estiverem presentes (por exemplo, no Binder ou no Code Engine, onde já vêm pré-instalados).

• Fornece um modelo de credenciais comentado para o IBM Quantum, para que os usuários que desejam executar em hardware real possam descomentar e preencher sua chave de API.

No Google Colab, essa célula é executada automaticamente ao abrir o notebook por meio da flag de metadados cell_execution_strategy: setup.

3. Reescrita de caminhos de imagens

Caminhos relativos de imagens (/docs/images/..., /learning/images/...) são reescritos para funcionar corretamente em ambientes de notebook independentes.

Páginas MDX (renderização no navegador)

Os tutoriais exibidos neste site são convertidos a partir de notebooks .ipynb upstream ou de arquivos .mdx. As seguintes transformações são aplicadas:

• Linhas pip install são adicionadas a blocos de código Python que importam pacotes de terceiros, possibilitando a execução com um clique via thebelab.

• Seção IBM Tutorial Survey: Uma nota é anexada esclarecendo que a pesquisa pertence ao IBM Quantum e direcionando para as Issues do GitHub da doQumentation para feedback específico do site.

• Widget de feedback: Um widget "Isto foi útil?" é anexado ao final de cada tutorial, monitorado pelo Umami analytics, que respeita a privacidade.

• Correções de sintaxe MDX: Chaves, hierarquia de cabeçalhos e problemas de compatibilidade com JSX são corrigidos automaticamente para a renderização no Docusaurus.

• OpenInLabBanner: Um banner interativo é injetado abaixo do título com botões para abrir o notebook no Colab, Binder ou Code Engine.

O que NÃO é modificado

• O conteúdo do tutorial em si (explicações, lógica do código, saídas) nunca é alterado.

• A atribuição original aos autores é preservada por meio do frontmatter e do arquivo NOTICE (licenças Apache 2.0 / CC BY-SA 4.0).

• Nenhum código de telemetria ou rastreamento é injetado nos notebooks. O analytics (Umami) é executado apenas no site da doQumentation, e não nos notebooks exportados.

Código-fonte

Todas as transformações são implementadas em scripts/sync-content.py.