자동 코드 수정

doQumentation은 원활하고 인터랙티브한 경험을 보장하기 위해 업스트림 Qiskit 튜토리얼 및 가이드 콘텐츠에 소수의 수정 사항을 자동으로 적용합니다. 이 페이지는 모든 수정 사항을 문서화하여 원본 IBM Quantum 문서와 비교하여 정확히 무엇이 변경되었는지 이해할 수 있도록 합니다.

노트북 복사본 (Colab / Binder / Code Engine에서 열기)

Open in Colab, Open in JupyterLab 또는 Open in Code Engine을 클릭하면 다음과 같은 추가 사항이 포함된 원본 노트북의 복사본을 받습니다:

1. 설정 안내 셀 (마크다운)

doQumentation이 자동 설정 셀을 추가했음을 설명하는 인용 블록 셀이 맨 위에 삽입됩니다. 이 페이지로 다시 링크됩니다.

2. 사전 준비 셀 (코드)

안내 셀 뒤에 다음과 같은 기능을 하는 코드 셀이 삽입됩니다:

• 필수 패키지 설치 (qiskit, qiskit-aer, qiskit-ibm-runtime, pylatexenc 및 import 스캔을 통해 감지된 튜토리얼별 패키지). 패키지가 이미 존재하는 경우(예: 사전 설치된 Binder 또는 Code Engine)에는 설치가 건너뛰어집니다.
• IBM Quantum용 주석 처리된 자격 증명 템플릿 제공. 실제 하드웨어에서 실행하려는 사용자는 주석을 해제하고 API 키를 입력할 수 있습니다.

Google Colab에서는 cell_execution_strategy: setup 메타데이터 플래그를 통해 노트북이 열릴 때 이 셀이 자동으로 실행됩니다.

3. 이미지 경로 재작성

상대 이미지 경로(/docs/images/..., /learning/images/...)는 독립 실행형 노트북 환경에서 올바르게 작동하도록 재작성됩니다.

MDX 페이지 (브라우저 내 렌더링)

이 웹사이트에 표시되는 튜토리얼은 업스트림 .ipynb 노트북 또는 .mdx 파일에서 변환됩니다. 다음 변환이 적용됩니다:

• 서드파티 패키지를 import하는 Python 코드 블록에 pip install 줄이 추가되어 thebelab을 통한 원클릭 실행이 가능합니다.
• IBM Tutorial Survey 섹션: 설문조사가 IBM Quantum에 속함을 명확히 하고 사이트별 피드백을 위해 doQumentation의 GitHub Issues로 연결하는 참고 사항이 추가됩니다.
• 피드백 위젯: 각 튜토리얼 하단에 "도움이 되었나요?" 위젯이 추가되며, 프라이버시 친화적인 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에 구현되어 있습니다.