\n\n\n[![Dependabot compatibility\nscore](https://dependabot-badges.githubapp.com/badges/compatibility_score?dependency-name=micromatch&package-manager=npm_and_yarn&previous-version=4.0.7&new-version=4.0.8)](https://docs.github.com/en/github/managing-security-vulnerabilities/about-dependabot-security-updates#about-compatibility-scores)\n\nDependabot will resolve any conflicts with this PR as long as you don't\nalter it yourself. You can also trigger a rebase manually by commenting\n`@dependabot rebase`.\n\n[//]: # (dependabot-automerge-start)\n[//]: # (dependabot-automerge-end)\n\n---\n\n\nDependabot commands and options
\n
\n\nYou can trigger Dependabot actions by commenting on this PR:\n- `@dependabot rebase` will rebase this PR\n- `@dependabot recreate` will recreate this PR, overwriting any edits\nthat have been made to it\n- `@dependabot merge` will merge this PR after your CI passes on it\n- `@dependabot squash and merge` will squash and merge this PR after\nyour CI passes on it\n- `@dependabot cancel merge` will cancel a previously requested merge\nand block automerging\n- `@dependabot reopen` will reopen this PR if it is closed\n- `@dependabot close` will close this PR and stop Dependabot recreating\nit. You can achieve the same result by closing it manually\n- `@dependabot show ignore conditions` will show all\nof the ignore conditions of the specified dependency\n- `@dependabot ignore major version` will close this\ngroup update PR and stop Dependabot creating any more for the specific\ndependency's major version (unless you unignore this specific\ndependency's major version or upgrade to it yourself)\n- `@dependabot ignore minor version` will close this\ngroup update PR and stop Dependabot creating any more for the specific\ndependency's minor version (unless you unignore this specific\ndependency's minor version or upgrade to it yourself)\n- `@dependabot ignore ` will close this group update PR\nand stop Dependabot creating any more for the specific dependency\n(unless you unignore this specific dependency or upgrade to it yourself)\n- `@dependabot unignore ` will remove all of the ignore\nconditions of the specified dependency\n- `@dependabot unignore ` will\nremove the ignore condition of the specified dependency and ignore\nconditions\nYou can disable automated security fix PRs for this repo from the\n[Security Alerts\npage](https://github.com/Qiskit/documentation/network/alerts).\n\n \n\nSigned-off-by: dependabot[bot] \nCo-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>","sha":"883c19845850d030f319364a33bb6a68ce7cbfb0","created_at":"2024-08-29 02:36","time_from_now":"2个月前","created_at_unix":1724870206}},{"name":"package.json","path":"package.json","sha":"4b50b3a0859ef8ffa1cb75ef84ee17322425d4fc","type":"file","submodule_git_url":null,"size":2890,"is_readme_file":null,"content":null,"target":null,"commit":{"message":"Add historical redirects file (#1780)\n\nAdds a file (and generation script) that links pages in historical API\ndocs to pages in the latest API docs. The banner we show on historical\ndocs pages can use this to link users to a more relevant page in the\nlatest docs, rather than always linking to the top level.\n\nThe file has the following form.\n\n```json\n{\n \"package-name\": {\n \"version\": {\n \"old.page.name\": \"new.page.name\",\n }\n }\n}\n```\n\nIf a page has no entry in the redirects file, we default to redirecting\nto the same page in the latest API docs. E.g.\n`/api/qiskit/0.33/qiskit.dagcircuit.DAGCircuit` will link to\n`/api/qiskit/qiskit.dagcircuit.DAGCircuit`.\n\nThis PR only checks if a page with the same name exists in the latest\nAPI docs and redirects to the top level if it does not. A follow up PR\ncould include more complicated logic to track moved classes or point to\nmodule names when the class is removed.\n\nStats
\n\nHere are some stats to give an idea of how many pages this affects.\n\nIn total, 35% of historical API pages have a corresponding page in the\nlatest API versions. Looking at the breakdown per version, the majority\nof recent pages will link to a more helpful page. The rest will behave\nthe same as before.\n\n| Package | Page matches |\n|---------|--------------|\n| qiskit-ibm-provider/0.10 | 100% |\n| qiskit-ibm-provider/0.7 | 100% |\n| qiskit-ibm-provider/0.8 | 100% |\n| qiskit-ibm-provider/0.9 | 100% |\n| qiskit-ibm-runtime/0.14 | 90% |\n| qiskit-ibm-runtime/0.15 | 90% |\n| qiskit-ibm-runtime/0.16 | 100% |\n| qiskit-ibm-runtime/0.17 | 100% |\n| qiskit-ibm-runtime/0.18 | 98% |\n| qiskit-ibm-runtime/0.19 | 98% |\n| qiskit-ibm-runtime/0.20 | 98% |\n| qiskit-ibm-runtime/0.21 | 99% |\n| qiskit-ibm-runtime/0.22 | 99% |\n| qiskit-ibm-runtime/0.23 | 100% |\n| qiskit-ibm-runtime/0.24 | 100% |\n| qiskit-ibm-runtime/dev | 100% |\n| qiskit/0.19 | 23% |\n| qiskit/0.24 | 23% |\n| qiskit/0.25 | 20% |\n| qiskit/0.26 | 20% |\n| qiskit/0.27 | 20% |\n| qiskit/0.28 | 21% |\n| qiskit/0.29 | 21% |\n| qiskit/0.30 | 21% |\n| qiskit/0.31 | 21% |\n| qiskit/0.32 | 21% |\n| qiskit/0.33 | 33% |\n| qiskit/0.35 | 34% |\n| qiskit/0.36 | 34% |\n| qiskit/0.37 | 34% |\n| qiskit/0.38 | 34% |\n| qiskit/0.39 | 34% |\n| qiskit/0.40 | 33% |\n| qiskit/0.41 | 33% |\n| qiskit/0.42 | 33% |\n| qiskit/0.43 | 39% |\n| qiskit/0.44 | 53% |\n| qiskit/0.45 | 56% |\n| qiskit/0.46 | 57% |\n| qiskit/1.0 | 97% |\n| qiskit/dev | 100% |\n\n \n\n---------\n\nCo-authored-by: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com>","sha":"60c437d9e57952e3f2592310cb26f87425b56b4a","created_at":"2024-07-31 01:19","time_from_now":"3个月前","created_at_unix":1722359961}},{"name":"qiskit_bot.yaml","path":"qiskit_bot.yaml","sha":"8501d25f8d0891043a3c2a2bd87fdb8fe425d495","type":"file","submodule_git_url":null,"size":9118,"is_readme_file":null,"content":null,"target":null,"commit":{"message":"add measurement information (#1988)\n\nCloses #1925\n\n---------\n\nCo-authored-by: Julien Gacon \nCo-authored-by: ABBY CROSS ","sha":"2cc007bdbdebf6b660f0a8436bd76e3671d7f869","created_at":"2024-10-04 21:36","time_from_now":"28天前","created_at_unix":1728048978}},{"name":"start","path":"start","sha":"c79cffe8006961bc554d3ea33130a3d7d359473a","type":"file","submodule_git_url":null,"size":1778,"is_readme_file":null,"content":null,"target":null,"commit":{"message":"Wait for docker pull in CI (#2023)\n\nCI can fail if `docker pull ...` takes longer than expected. This PR\nadds a `--pull-only` option to `./start`, then waits for it to complete\nin CI.","sha":"a43cab83755319e0e0c13a43583367a7b21af528","created_at":"2024-09-24 23:17","time_from_now":"1个月前","created_at_unix":1727191049}},{"name":"style-guide.md","path":"style-guide.md","sha":"2313736cefe08540dec11dd5e878749f6912ac0e","type":"file","submodule_git_url":null,"size":4376,"is_readme_file":0,"content":null,"target":null,"commit":{"message":"Update style-guide.md: Remove redundant list item (#1399)\n\n","sha":"1ca51e8f6dec2b930fa45f89ad1e4d7909483017","created_at":"2024-05-17 04:28","time_from_now":"6个月前","created_at_unix":1715891326}},{"name":"tox.ini","path":"tox.ini","sha":"f37baaba62684eb392e10680737b9c71a1951f76","type":"file","submodule_git_url":null,"size":507,"is_readme_file":null,"content":null,"target":null,"commit":{"message":"Restore Serverless 0.15.2 and test notebooks when changing requirements (#1831)\n\nCloses https://github.com/Qiskit/documentation/issues/1826.\n\n## Switches to Python 3.11\n\nQiskit Serverless requires Python 3.11+ now, even though Qiskit SDK\nstill supports 3.9 and 3.10. While I'm talking to the Serverless team,\nit seems very unlikely they are going to change their mind on this due\nto their own constraints.\n\nUnfortunately, this means that we need to always use Python 3.11 with\nour repository so that we can install serverless for the files that use\nit. Our other alternative is to stop testing the files with Serverless,\nbut that seems even worse.\n\nThe risk with using 3.11 in CI rather than 3.9 is that we may use syntax\nnot in Python 3.9 and 3.10. However, given the actual history of our\ndocs, this seems unlikely: we don't use new Python syntax like type\nhints. If we do use Python 3.11-syntax, it's not the end of the world.\n\n## Tests all notebooks on changes to requirements.txt\n\nThis was an oversight that we would not test the notebooks when changing\nrequirements.txt. So, we merged a change that worked locally but broke\nCI. Now, we test all notebooks when the nb-tester program and config\nchanges.\n\n## Also upgrades Runtime\n\nThis is necessary to make Serverless happy. According to\nhttps://docs.quantum.ibm.com/api/qiskit-ibm-runtime/release-notes#0270-2024-08-08,\nthere are no breaking changes. CI also shows everything passes.","sha":"fed9ca745d4ef7cb31503371dfadbc874bfdfe45","created_at":"2024-08-15 05:57","time_from_now":"3个月前","created_at_unix":1723672677}},{"name":"tsconfig.json","path":"tsconfig.json","sha":"aeebbc2ef2170411e6403236290fa6f5a8294c6d","type":"file","submodule_git_url":null,"size":327,"is_readme_file":null,"content":null,"target":null,"commit":{"message":"Allow running `scripts/js` from other Node projects (#1747)\n\nThis PR allows other repositories to depend on this repo as a VCS\nrequirement, then to run our scripts, like this:\n\n```json\n \"scripts\": {\n \"check\": \"node node_modules/qiskit-documentation/dist/commands/checkMetadata.js\"\n },\n \"dependencies\": {\n \"qiskit-documentation\": \"qiskit/documentation#3422358984f9ede3a6ac8a2bbe7df517fbd306cb\"\n },\n```\n\n```\n❯ npm run check \n\n> my-function-docs@0.1.0 check:metadata\n> node node_modules/qiskit-documentation/dist/commands/checkMetadata.js\n```\n\n`node_modules/qiskit-documentation` will include only the contents of\n`src/js` but compiled to JavaScript, along with `package.json`. That\nresults in the other project bringing in all of the transitive\ndependencies of this repo.\n\nRunning scripts locally still works.\n\n## Migration to ES Modules\n\nBefore, we were using CommonJS for how imports and module loading works.\nHowever, this was causing issues when trying to run in other repos. The\neasiest fix was to migrate to ES Modules by setting `\"type\": \"module\"`\nin `package.json`.\n\nThis required that we set a `.js` file extension in all of our import\nstatements, and that we use `lodash-es` rather than `lodash`.\n\n## Migration to Playwright\n\nI could not get Jest to play nicely with TypeScript & ES Modules. The\nsimplest fix was to migrate to Playwright.\n\nWe already use Playwright in qiskit-sphinx-theme, so this brings nice\nconsistency to the open source projects.\n\n## Followup work: fix individual scripts\n\nSome of the scripts may need changes to work in other repositories, like\nour internal link checker. For now, `checkMetadata.ts` and\n`checkExternalLinks.ts` definitely work.","sha":"8f49061837e6392d6f8eb0d90735f5f776e4ae13","created_at":"2024-07-24 01:19","time_from_now":"3个月前","created_at_unix":1721755164}}]},"projectMenu":[{"menu_name":"home"},{"menu_name":"code"},{"menu_name":"issues"},{"menu_name":"devops"},{"menu_name":"versions"},{"menu_name":"wiki"},{"menu_name":"resources"},{"menu_name":"activity"}],"projectReadMe":"%7B%22type%22%3A%22file%22%2C%22encoding%22%3A%22base64%22%2C%22size%22%3A31748%2C%22name%22%3A%22README.md%22%2C%22path%22%3A%22README.md%22%2C%22content%22%3A%22%23%20Qiskit%20documentation%5Cn%5CnThe%20documentation%20content%20home%20for%20https%3A%2F%2Fdocs.quantum.ibm.com%20(excluding%20API%20reference).%5Cn%5Cn%23%20Improving%20IBM%20Quantum%20%26%20Qiskit%20Documentation%5Cn%5CnMaintaining%20up-to-date%20documentation%20is%20a%20huge%20challenge%20for%20any%20software%20project%2C%20especially%20in%20a%20field%20like%20quantum%20computing%20where%20the%20pace%20at%20which%20advances%20in%20new%20research%20and%20technological%20capabilities%20happen%20incredibly%20fast.%20As%20a%20result%2C%20we%20greatly%20appreciate%20any%20who%20take%20the%20time%20to%20support%20us%20in%20keeping%20this%20content%20accurate%20and%20up%20to%20the%20highest%20quality%20standard%20possible%20to%20benefit%20the%20broadest%20range%20of%20users.%5Cn%5CnRead%20on%20for%20more%20information%20about%20how%20to%20support%20this%20project%3A%5Cn%5Cn%23%23%20Best%20ways%20to%20contribute%20to%20Documentation%5Cn%5Cn%23%23%23%201.%20Report%20bugs%2C%20inaccuracies%20or%20general%20content%20issues%5Cn%5CnThis%20is%20the%20quickest%2C%20easiest%2C%20and%20most%20helpful%20way%20to%20contribute%20to%20this%20project%20and%20improve%20the%20quality%20of%20Qiskit%26reg%3B%20and%20IBM%20Quantum%26trade%3B%20documentation.%20There%20are%20a%20few%20different%20ways%20to%20report%20issues%2C%20depending%20on%20where%20it%20was%20found%3A%5Cn%5Cn-%20For%20problems%20you've%20found%20in%20the%20%5BQiskit%20SDK%20API%20Reference%5D(https%3A%2F%2Fdocs.quantum.ibm.com%2Fapi%2Fqiskit)%20section%2C%20open%20an%20issue%20in%20the%20Qiskit%20repo%20%5Bhere%5D(https%3A%2F%2Fgithub.com%2FQiskit%2Fqiskit%2Fissues%2Fnew%2Fchoose).%5Cn-%20For%20problems%20you've%20found%20in%20the%20%5BQiskit%20Runtime%20Client%5D(https%3A%2F%2Fdocs.quantum.ibm.com%2Fapi%2Fqiskit-ibm-runtime)%20section%2C%20open%20an%20issue%20in%20the%20Qiskit%20IBM%20Runtime%20repo%20%5Bhere%5D(https%3A%2F%2Fgithub.com%2FQiskit%2Fqiskit-ibm-runtime%2Fissues%2Fnew%2Fchoose).%5Cn-%20For%20problems%20you've%20found%20in%20any%20other%20section%20of%20%5Bdocs%5D(https%3A%2F%2Fdocs.quantum.ibm.com)%2C%20open%20a%20content%20bug%20issue%20%5Bhere%5D(https%3A%2F%2Fgithub.com%2FQiskit%2Fdocumentation%2Fissues%2Fnew%2Fchoose).%5Cn%5Cn%23%23%23%202.%20Suggest%20new%20content%5Cn%5CnIf%20you%20think%20there%20are%20gaps%20in%20our%20documentation%2C%20or%20sections%20that%20could%20be%20expanded%20upon%2C%20we%20invite%20you%20to%20open%20a%20new%20content%20request%20issue%20%5Bhere%5D(https%3A%2F%2Fgithub.com%2FQiskit%2Fdocumentation%2Fissues%2Fnew%2Fchoose).%5Cn%5CnNot%20every%20new%20content%20suggestion%20is%20a%20good%20fit%20for%20docs%2C%20nor%20are%20we%20able%20to%20prioritize%20every%20request%20immediately.%20However%2C%20we%20will%20do%20our%20best%20to%20respond%20to%20content%20requests%20in%20a%20timely%20manner%2C%20and%20we%20greatly%20appreciate%20our%20community's%20efforts%20in%20generating%20new%20ideas.%5Cn%5CnIf%20you%20are%20interested%20in%20writing%20the%20new%20content%20yourself%2C%20or%20already%20have%20some%20draft%20work%20you%20think%20could%20be%20integrated%2C%20please%20also%20mention%20that%20in%20the%20issue%20description.%20If%20your%20content%20suggestion%20is%20accepted%2C%20we%20will%20let%20you%20know%20and%20work%20with%20you%20to%20get%20the%20content%20written%20and%20reviewed.%5Cn%5CnPlease%20note%3A%20we%20DO%20NOT%20accept%20unsolicited%20PRs%20for%20new%20pages%20or%20large%20updates%20to%20existing%20content.%20The%20content%20that%20we%20include%20in%20docs%20is%20carefully%20planned%20and%20curated%20by%20our%20content%20team%20and%20must%20go%20through%20the%20appropriate%20review%20process%20to%20ensure%20the%20quality%20is%20of%20the%20highest%20possible%20standard%20before%20deploying%20to%20production.%20As%20a%20result%20we%20are%20very%20selective%20with%20which%20content%20suggestions%20are%20approved%2C%20and%20it%20is%20unlikely%20that%20PRs%20submitted%20without%20an%20associated%20approved%20content%20request%20will%20be%20accepted.%5Cn%5Cn%23%23%23%203.%20Validate%20existing%20issues%5Cn%5CnYou%20can%20help%20the%20team%20prioritize%20already-open%20issues%20by%20doing%20the%20following%3A%5Cn%5Cn-%20For%20bug%20reports%2C%20leave%20a%20comment%20in%20the%20issue%20if%20you%20have%20also%20been%20experiencing%20the%20same%20problem%20and%20can%20reproduce%20it%20(include%20as%20much%20information%20as%20you%20can%2C%20e.g.%2C%20browser%20type%2C%20Qiskit%20version%2C%20etc.).%5Cn-%20For%20new%20content%20requests%2C%20leave%20a%20comment%20or%20upvote%20(%F0%9F%91%8D)%20in%20the%20issue%20if%20you%20also%20would%20like%20to%20see%20that%20new%20content%20added.%5Cn%5Cn%23%23%23%204.%20Fix%20an%20open%20issue%5Cn%5CnYou%20can%20look%20through%20the%20open%20issues%20we%20have%20in%20this%20repo%20and%20address%20them%20with%20a%20PR.%20We%20recommend%20focusing%20on%20issues%20with%20the%20%5C%22good%20first%20issue%5C%22%20label.%5Cn%5CnBefore%20getting%20started%20on%20an%20issue%2C%20remember%20to%20do%20the%20following%3A%5Cn%5Cn1.%20Read%20the%20%5BCode%20of%20Conduct%5D(https%3A%2F%2Fdocs.quantum.ibm.com%2Fopen-source%2Fcode-of-conduct)%5Cn2.%20Check%20for%20open%2C%20unassigned%20issues%20with%20the%20%5C%22good%20first%20issue%5C%22%20label%5Cn3.%20Select%20an%20issue%20that%20is%20not%20already%20assigned%20to%20someone%20and%20leave%20a%20comment%20to%20request%20to%20be%20assigned%5Cn%5CnOnce%20you%20have%20an%20issue%20to%20work%20on%2C%20see%20the%20%5C%22How%20to%20work%20with%20this%20repo%5C%22%20section%20below%20to%20get%20going%2C%20then%20open%20a%20PR.%5Cn%5CnBefore%20opening%20a%20PR%2C%20remember%20to%20do%20the%20following%3A%5Cn%5Cn1.%20Check%20that%20you%20have%20addressed%20all%20the%20requirements%20from%20the%20original%20issue%5Cn2.%20Run%20the%20quality%20control%20checks%20with%20%60npm%20run%20check%60%5Cn3.%20Use%20the%20GitHub%20%5C%22fixes%5C%22%20notation%20to%20%5Blink%20your%20PR%20to%20the%20issue%5D(https%3A%2F%2Fdocs.github.com%2Fen%2Fissues%2Ftracking-your-work-with-issues%2Flinking-a-pull-request-to-an-issue)%20you%20are%20addressing%5Cn%5Cn%23%20How%20to%20work%20with%20this%20repo%5Cn%5Cn%23%23%20Prerequisites%20to%20building%20the%20docs%20locally%5Cn%5CnThese%20tools%20will%20also%20run%20in%20CI%2C%20but%20it%20can%20be%20convenient%20when%20iterating%20to%20run%20the%20tools%20locally.%5Cn%5CnFirst%2C%20install%20the%20below%20software%3A%5Cn%5Cn1.%20%5BNode.js%5D(https%3A%2F%2Fnodejs.org%2Fen).%20If%20you%20expect%20to%20use%20JavaScript%20in%20other%20projects%2C%20consider%20using%20%5BNVM%5D(https%3A%2F%2Fgithub.com%2Fnvm-sh%2Fnvm).%20Otherwise%2C%20consider%20using%20%5BHomebrew%5D(https%3A%2F%2Fformulae.brew.sh%2Fformula%2Fnode)%20or%20installing%20%5BNode.js%20directly%5D(https%3A%2F%2Fnodejs.org%2Fen).%5Cn2.%20%5BDocker%5D(https%3A%2F%2Fwww.docker.com).%20You%20must%20also%20ensure%20that%20it%20is%20running.%5Cn%20%20%20-%20If%20you%20cannot%20use%20Docker%20from%20docker.com%2C%20consider%20using%20use%20%5BColima%5D(https%3A%2F%2Fgithub.com%2Fabiosoft%2Fcolima)%20or%20%5BRancher%20Desktop%5D(https%3A%2F%2Francherdesktop.io).%20When%20installing%20Rancher%20Desktop%2C%20choose%20Moby%2FDockerd%20as%20the%20engine%2C%20rather%20than%20nerdctl.%20To%20ensure%20it's%20running%2C%20open%20up%20the%20app%20%5C%22Rancher%20Desktop%5C%22.%5Cn%5CnThen%2C%20install%20the%20dependencies%20with%3A%5Cn%5Cn%60%60%60bash%5Cnnpm%20install%5Cn%60%60%60%5Cn%5Cn%23%23%20Preview%20the%20docs%20locally%5Cn%5CnYou%20can%20preview%20the%20docs%20locally%20by%20following%20these%20two%20steps%3A%5Cn%5Cn1.%20Ensure%20Docker%20is%20running.%20For%20example%2C%20open%20Rancher%20Desktop.%5Cn2.%20Run%20%60.%2Fstart%60%20in%20your%20terminal%2C%20and%20open%20http%3A%2F%2Flocalhost%3A3000%20in%20your%20browser.%5Cn%5CnThe%20preview%20application%20does%20not%20include%20the%20top%20nav%20bar.%20Instead%2C%20navigate%20to%20the%20folder%20you%20want%20with%20the%20links%20in%20the%20home%20page.%20You%20can%20return%20to%20the%20home%20page%20at%20any%20time%20by%20clicking%20%5C%22IBM%20Quantum%20Documentation%20Preview%5C%22%20in%20the%20top-left%20of%20the%20header.%5Cn%5CnWarning%3A%20%60.%2Fstart%60%20does%20not%20check%20if%20there%20is%20a%20new%20version%20of%20the%20docs%20application%20available.%20You%20can%20run%20%60docker%20pull%20qiskit%2Fdocumentation%60%20to%20update%20to%20the%20latest%20version%20of%20the%20app.%20It%20will%20also%20ignore%20the%20API%20docs%20to%20speed%20things%20up%2C%20if%20you%20want%20to%20view%20them%2C%20run%20%60.%2Fstart%20--apis%60.%5Cn%5Cn%23%23%23%20API%20docs%20authors%3A%20How%20to%20preview%20your%20changes%5Cn%5CnAPI%20docs%20authors%20can%20preview%20their%20changes%20to%20one%20of%20the%20APIs%20by%20using%20the%20%60-a%60%20parameter%20to%20specify%20the%20path%20to%20the%20docs%20folder%3A%5Cn%5Cn1.%20Run%20%60npm%20run%20gen-api%20--%20-p%20%3Cpkg-name%3E%20-v%20%3Cversion%3E%20-a%20%3Cpath%2Fto%2Fdocs%2F_build%2Fhtml%3E%60.%5Cn2.%20Execute%20%60.%2Fstart%60%20and%20open%20up%20%60http%3A%2F%2Flocalhost%3A3000%60%2C%20as%20explained%20in%20the%20prior%20section.%5Cn%5Cn%23%23%20Jupyter%20notebooks%5Cn%5Cn%23%23%23%20Add%20a%20new%20notebook%5Cn%5CnWhen%20adding%20a%20new%20notebook%2C%20you'll%20need%20to%20tell%20the%20testing%20tools%20how%20to%20handle%20it.%5CnTo%20do%20this%2C%20add%20the%20file%20path%20to%20%60scripts%2Fconfig%2Fnotebook-testing.toml%60.%20There%20are%5Cnfour%20categories%3A%5Cn%5Cn-%20%60notebooks_normal_test%60%3A%20Notebooks%20to%20be%20run%20normally%20in%20CI.%20These%20notebooks%5Cn%20%20can't%20submit%20jobs%20as%20the%20queue%20times%20are%20too%20long%20and%20it%20will%20waste%5Cn%20%20resources.%20You%20_can_%20interact%20with%20IBM%20Quantum%20to%20retrieve%20jobs%20and%20backend%5Cn%20%20information.%5Cn-%20%60notebooks_that_submit_jobs%60%3A%20Notebooks%20that%20submit%20jobs%2C%20but%20that%20are%20small%5Cn%20%20enough%20to%20run%20on%20a%205-qubit%20simulator.%20We%20will%20test%20these%20notebooks%20in%20CI%20by%5Cn%20%20patching%20%60least_busy%60%20to%20return%20a%205-qubit%20fake%20backend.%5Cn-%20%60notebooks_no_mock%60%3A%20For%20notebooks%20that%20can't%20be%20tested%20using%20the%205-qubit%5Cn%20%20simulator%20patch.%20We%20skip%20testing%20these%20in%20CI%20and%20instead%20run%20them%20twice%20per%5Cn%20%20month.%20Any%20notebooks%20with%20cells%20that%20take%20more%20than%20five%20minutes%20to%20run%20are%5Cn%20%20also%20deemed%20too%20big%20for%20CI.%20Try%20to%20avoid%20adding%20notebooks%20to%20this%20category%20if%5Cn%20%20possible.%5Cn-%20%60notebooks_exclude%60%3A%20Notebooks%20to%20be%20ignored.%5Cn%5CnIf%20your%20notebook%20uses%20the%20latex%20circuit%20drawer%20(%60qc.draw(%5C%22latex%5C%22)%60)%2C%20you%20must%5Cnalso%20add%20it%20to%20the%20%5C%22Check%20for%20notebooks%20that%20require%20LaTeX%5C%22%20step%20in%5Cn%60.github%2Fworkflows%2Fnotebook-test.yml%60.%5Cn%5Cn%23%23%23%20Execute%20notebooks%5Cn%5CnBefore%20submitting%20a%20new%20notebook%20or%20code%20changes%20to%20a%20notebook%2C%20you%20must%20run%5Cnthe%20notebook%20using%20%60tox%20--%20--write%20%3Cpath-to-notebook%3E%60%20and%20commit%20the%20results.%5CnIf%20the%20notebook%20submits%20jobs%2C%20also%20use%20the%20argument%20%60--submit-jobs%60.%20This%20means%5Cnwe%20can%20be%20sure%20all%20notebooks%20work%20and%20that%20users%20will%20see%20the%20same%20results%20when%5Cnthey%20run%20using%20the%20environment%20we%20recommend.%5Cn%5CnTo%20execute%20notebooks%20in%20a%20fixed%20Python%20environment%2C%20first%20install%20%60tox%60%20using%5Cn%5Bpipx%5D(https%3A%2F%2Fpipx.pypa.io%2Fstable%2F)%3A%5Cn%5Cn%60%60%60sh%5Cnpipx%20install%20tox%5Cn%60%60%60%5Cn%5CnYou%20also%20need%20to%20install%20a%20few%20system%20dependencies%3A%20TeX%2C%20Poppler%2C%20and%20graphviz.%5CnOn%20macOS%2C%20you%20can%20run%20%60brew%20install%20mactex-no-gui%20poppler%20graphviz%60.%20On%20Ubuntu%2C%5Cnyou%20can%20run%20%60apt-get%20install%20texlive-pictures%20texlive-latex-extra%20poppler-utils%5Cngraphviz%60.%5Cn%5Cn-%20To%20execute%20all%20notebooks%2C%20run%20tox.%5Cn%20%20%60%60%60sh%5Cn%20%20tox%5Cn%20%20%60%60%60%5Cn-%20To%20only%20execute%20specific%20notebooks%2C%20pass%20them%20as%20arguments.%5Cn%20%20%60%60%60sh%5Cn%20%20tox%20--%20path%2Fto%2Fnotebook.ipynb%20path%2Fto%2Fanother-notbook.ipynb%5Cn%20%20%60%60%60%5Cn-%20To%20write%20the%20execution%20results%20to%20the%20file%2C%20pass%20the%20%60--write%60%20argument.%5Cn%20%20%60%60%60sh%5Cn%20%20tox%20--%20optional%2Fpaths%2Fto%2Fnotebooks.ipynb%20--write%5Cn%20%20%60%60%60%5Cn%5CnWhen%20you%20make%20a%20pull%20request%20changing%20a%20notebook%20that%20doesn't%20submit%20jobs%2C%20you%5Cncan%20get%20a%20version%20of%20that%20notebook%20that%20was%20executed%20by%20tox%20from%20CI.%20To%20do%5Cnthis%2C%20click%20%5C%22Show%20all%20checks%5C%22%20in%20the%20info%20box%20at%20the%20bottom%20of%20the%20pull%20request%5Cnpage%20on%20GitHub%2C%20then%20choose%20%5C%22Details%5C%22%20for%20the%20%5C%22Test%20notebooks%5C%22%20job.%20From%20the%5Cnjob%20page%2C%20click%20%5C%22Summary%5C%22%2C%20then%20download%20%5C%22Executed%20notebooks%5C%22.%20Otherwise%2C%20if%5Cnyour%20notebook%20does%20submit%20jobs%2C%20you%20need%20to%20run%20it%20locally%20using%20the%20steps%5Cnmentioned%20earlier.%5Cn%5Cn%23%23%23%20Ignore%20warnings%20in%20your%20notebook%5Cn%5CnWe%20don't%20want%20users%20to%20see%20warnings%20that%20can%20be%20avoided%2C%20so%20it's%20best%20to%20fix%5Cnthe%20code%20to%20avoid%20them.%20However%2C%20if%20a%20warning%20is%20unavoidable%2C%20you%20can%20stop%20it%5Cnblocking%20CI%20by%20adding%20an%20%60ignore-warnings%60%20tag%20to%20the%20cell.%20In%20VSCode%2C%5Cnright-click%20the%20cell%2C%20choose%20%5C%22Add%20cell%20tag%5C%22%2C%20type%20%60ignore-warnings%60%2C%20then%20press%5Cn%5C%22Enter%5C%22.%20In%20Jupyter%20notebook%20(depending%20on%20version)%2C%20choose%20View%20%3E%20Right%5CnSidebar%20%3E%20Show%20Notebook%20Tools%2C%20then%20under%20%5C%22Common%20Tools%5C%22%20add%20a%20tag%20with%20text%5Cn%60ignore-warnings%60.%5Cn%5Cn%23%23%23%20Add%20extra%20code%20checks%20to%20your%20notebook%5Cn%5CnOur%20CI%20checks%20notebooks%20run%20from%20start%20to%20finish%20without%20errors%20or%20warnings.%5CnYou%20can%20add%20extra%20checks%20in%20notebooks%20to%20catch%20other%20unexpected%20behavior.%5Cn%5CnFor%20example%2C%20say%20we%20claim%20a%20cell%20always%20returns%20the%20string%20%600011%60.%20It%20would%20be%5Cnembarassing%20if%20this%20was%20not%20true.%20We%20can%20assert%20this%20in%20CI%20by%20adding%20the%5Cnfollowing%20code%20cell%2C%20and%20hide%20it%20from%20users%20with%20a%20%60remove-cell%60%20tag.%5Cn%5Cn%60%60%60python%5Cn%23%20Confirm%20output%20is%20what%20we%20expect.%5Cnassert%20_%20%3D%3D%20'0011'%5Cn%60%60%60%5Cn%5CnIn%20Jupyter%20notebooks%2C%20the%20underscore%20%60_%60%20variable%20stores%20the%20value%20of%20the%5Cnprevious%20cell%20output.%20You%20should%20also%20add%20a%20comment%20like%5Cn%60%23%20Confirm%20output%20is%20what%20we%20expect%60%20so%20that%20authors%20know%20this%5Cnblock%20is%20only%20for%20testing.%20Make%20sure%20you%20add%20the%20tag%20%60remove-cell%60.%5CnIf%20something%20ever%20causes%20this%20value%20to%5Cnchange%2C%20CI%20will%20alert%20us.%5Cn%5Cn%23%23%23%20Lint%20notebooks%5Cn%5CnWe%20use%20%5B%60squeaky%60%5D(https%3A%2F%2Fgithub.com%2Ffrankharkins%2Fsqueaky)%20to%20lint%20our%5Cnnotebooks.%20First%20install%20%60tox%60%20using%20%5Bpipx%5D(https%3A%2F%2Fpipx.pypa.io%2Fstable%2F).%5Cn%5Cn%60%60%60sh%5Cnpipx%20install%20tox%5Cn%60%60%60%5Cn%5CnTo%20check%20if%20a%20notebook%20needs%20linting%3A%5Cn%5Cn%60%60%60sh%5Cn%23%20Check%20all%20notebooks%20in%20.%2Fdocs%5Cntox%20-e%20lint%20--%20docs%2F**%2F*.ipynb%5Cn%60%60%60%5Cn%5CnTo%20fix%20problems%20in%20a%20notebooks%2C%20run%3A%5Cn%5Cn%60%60%60sh%5Cntox%20-e%20fix%20--%20path%2Fto%2Fnotebook%5Cn%60%60%60%5Cn%5CnOr%2C%20you%20can%20retrieve%20an%20executed%20and%20linted%20version%20of%20your%20notebook%20from%20CI%5Cnfollowing%20the%20steps%20at%20the%20end%20of%20the%20%5BExecute%20notebooks%5D(%23execute-notebooks)%5Cnsection.%5Cn%5CnIf%20you%20use%20the%20Jupyter%20notebook%20editor%2C%20consider%20adding%20squeaky%20as%20a%20%5Bpre-save%5Cnhook%5D(https%3A%2F%2Fgithub.com%2Ffrankharkins%2Fsqueaky%3Ftab%3Dreadme-ov-file%23jupyter-pre-save-hook).%5CnThis%20will%20lint%20your%20notebooks%20as%20you%20save%20them%2C%20so%20you%20never%20need%20to%20worry%5Cnabout%20it.%5Cn%5Cn%23%23%20Check%20for%20broken%20links%5Cn%5CnWe%20have%20two%20broken%20link%20checkers%3A%20for%20internal%20links%20and%20for%20external%20links.%5Cn%5CnTo%20check%20internal%20links%3A%5Cn%5Cn%60%60%60bash%5Cn%23%20Only%20check%20non-API%20docs%5Cnnpm%20run%20check%3Ainternal-links%5Cn%5Cn%23%20You%20can%20add%20any%20of%20the%20below%20arguments%20to%20also%20check%20API%20docs.%5Cnnpm%20run%20check%3Ainternal-links%20--%20--current-apis%20--dev-apis%20--historical-apis%20--qiskit-legacy-release-notes%5Cn%5Cn%23%20Or%2C%20run%20all%20the%20checks.%20Although%20this%20only%20checks%20non-API%20docs.%5Cnnpm%20run%20check%5Cn%60%60%60%5Cn%5CnTo%20check%20external%20links%3A%5Cn%5Cn%60%60%60bash%5Cn%23%20Specify%20the%20files%20you%20want%20after%20%60--%60%5Cnnpm%20run%20check%3Aexternal-links%20--%20docs%2Fguides%2Findex.md%20docs%2Fguides%2Fcircuit-execution.mdx%5Cn%5Cn%23%20You%20can%20also%20use%20globs%5Cnnpm%20run%20check%3Aexternal-links%20--%20'docs%2Fguides%2F*'%20'!docs%2Fguides%2Findex.mdx'%5Cn%60%60%60%5Cn%5Cn%23%23%20Check%20for%20orphan%20pages%5Cn%5CnEvery%20file%20should%20have%20a%20home%20in%20one%20of%20the%20%60_toc.json%60%20files.%5Cn%5CnTo%20check%20for%20orphaned%20pages%2C%20run%3A%5Cn%5Cn%60%60%60bash%5Cn%23%20Only%20check%20non-API%20docs%5Cnnpm%20run%20check%3Aorphan-pages%5Cn%5Cn%23%20You%20can%20also%20check%20API%20docs%5Cnnpm%20run%20check%3Aorphan-pages%20--%20--apis%5Cn%5Cn%23%20Or%2C%20run%20all%20the%20checks.%20However%20this%20will%20skip%20the%20API%20docs%5Cnnpm%20run%20check%5Cn%60%60%60%5Cn%5Cn%23%23%20Check%20page%20metadata%5Cn%5CnEvery%20file%20needs%20to%20have%20a%20%60title%60%20and%20%60description%60%2C%20as%20explained%20in%20%5BPage%20Metadata%5D(%23page-metadata)%20The%20%60lint%60%20job%20in%20CI%20will%20fail%20with%20instructions%20for%20any%20bad%20file.%5Cn%5CnYou%20can%20also%20check%20for%20valid%20metadata%20locally%3A%5Cn%5Cn%60%60%60bash%5Cn%23%20Only%20check%20file%20metadata%5Cnnpm%20run%20check%3Ametadata%5Cn%5Cn%23%20By%20default%2C%20only%20the%20non-API%20docs%20are%20checked.%20You%20can%20add%20the%5Cn%23%20below%20argument%20to%20also%20check%20API%20docs.%5Cnnpm%20run%20check%3Ametadata%20--%20--apis%5Cn%5Cn%23%20Or%2C%20run%20all%20the%20checks.%20Although%20this%20only%20checks%20non-API%20docs.%5Cnnpm%20run%20check%5Cn%60%60%60%5Cn%5Cn%23%23%20Spellcheck%5Cn%5CnWe%20use%20%5BcSpell%5D(https%3A%2F%2Fcspell.org)%20to%20check%20for%20spelling.%20The%20%60lint%60%20job%20in%20CI%20will%20fail%20if%20there%20are%20spelling%20issues.%5Cn%5CnThere%20are%20two%20ways%20to%20check%20spelling%20locally%2C%20rather%20than%20needing%20CI.%5Cn%5Cn1.%5Cn%5Cn%60%60%60bash%5Cn%23%20Only%20check%20spelling%5Cnnpm%20run%20check%3Aspelling%5Cn%5Cn%23%20Or%2C%20run%20all%20the%20checks%5Cnnpm%20run%20check%5Cn%60%60%60%5Cn%5Cn2.%20Use%20the%20VSCode%20extension%20%5BCode%20Spell%20Checker%5D(https%3A%2F%2Fmarketplace.visualstudio.com%2Fitems%3FitemName%3Dstreetsidesoftware.code-spell-checker).%5Cn%5Cn%23%23%23%20Fixing%20false%20positives%5Cn%5CnThere%20are%20two%20ways%20to%20deal%20with%20cSpell%20incorrectly%20complaining%20about%20a%20word%2C%20such%20as%20abbreviations.%5Cn%5Cn1.%20Ignore%20the%20word%20in%20the%20local%20markdown%20file%20by%20adding%20a%20comment%20to%20the%20file%2C%20like%20below.%20The%20word%20is%20not%20case-sensitive%2C%20and%20the%20comment%20can%20be%20placed%20anywhere.%5Cn%5Cn%60%60%60%5Cn%7B%2F*%20cspell%3Aignore%20hellllooooo%2C%20ayyyyy%20*%2F%7D%5Cn%5Cn%23%20Hellllooooo!%5Cn%5CnAyyyyy%2C%20this%20is%20a%20fake%20description.%5Cn%60%60%60%5Cn%5Cn2.%20If%20the%20word%20is%20a%20name%2C%20add%20it%20to%20the%20%60scripts%2Fconfig%2Fcspell%2Fdictionaries%2Fpeople.txt%60%20file.%20If%20it%20is%20a%20scientific%20or%20quantum%20specific%20word%2C%20add%20it%20to%20the%20%60scripts%2Fconfig%2Fcspell%2Fdictionaries%2Fqiskit.txt%60%20file.%20If%20it%20doesn't%20fit%20in%20either%20category%2C%20add%20it%20to%20the%20%60words%60%20section%20in%20%60scripts%2Fconfig%2Fcspell%2FcSpell.json%60.%20The%20word%20is%20not%20case-sensitive.%5Cn%5CnIf%20the%20word%20appears%20in%20multiple%20files%2C%20prefer%20the%20second%20approach%20to%20add%20it%20to%20one%20of%20the%20dictionaries%20or%20%60cSpell.json%60.%5Cn%5Cn%23%23%20Check%20that%20pages%20render%5Cn%5CnIt's%20possible%20to%20write%20broken%20pages%20that%20crash%20when%20loaded.%20This%20is%20usually%20due%20to%20syntax%20errors.%5Cn%5CnTo%20check%20that%20all%20the%20non-API%20docs%20render%3A%5Cn%5Cn1.%20Start%20up%20the%20local%20preview%20with%20%60.%2Fstart%60%20by%20following%20the%20instructions%20at%20%5BPreview%20the%20docs%20locally%5D(%23preview-the-docs-locally)%5Cn2.%20In%20a%20new%20tab%2C%20%60npm%20run%20check%3Apages-render%20--%20--non-api%60%5Cn%5CnYou%20can%20also%20check%20that%20API%20docs%20render%20by%20using%20any%20of%20these%20arguments%3A%20%60npm%20run%20check%3Apages-render%20--%20--non-api%20--qiskit-release-notes%20--current-apis%20--dev-apis%20--historical-apis%60.%20Warning%20that%20this%20is%20exponentially%20slower.%5Cn%5CnCI%20will%20check%20on%20every%20PR%20that%20any%20changed%20files%20render%20correctly.%20We%20also%20run%20a%20weekly%20cron%20job%20to%20check%20that%20every%20page%20renders%20correctly.%5Cn%5Cn%23%23%20Format%20README%20and%20TypeScript%20files%5Cn%5CnRun%20%60npm%20run%20fmt%60%20to%20automatically%20format%20the%20README%2C%20%60.github%60%20folder%2C%20and%20%60scripts%2F%60%20folder.%20You%20should%20run%20this%20command%20if%20you%20get%20the%20error%20in%20CI%20%60run%20Prettier%20to%20fix%60.%5Cn%5CnTo%20check%20that%20formatting%20is%20valid%20without%20actually%20making%20changes%2C%20run%20%60npm%20run%20check%3Afmt%60%20or%20%60npm%20run%20check%60.%5Cn%5Cn%23%23%20Regenerate%20an%20existing%20API%20docs%20version%5Cn%5CnThis%20is%20useful%20when%20we%20make%20improvements%20to%20the%20API%20generation%20script.%5Cn%5CnYou%20can%20regenerate%20all%20API%20docs%20versions%20following%20these%20steps%3A%5Cn%5Cn1.%20Create%20a%20dedicated%20branch%20for%20the%20regeneration%20other%20than%20%60main%60%20using%20%60git%20checkout%20-b%20%3Cbranch-name%3E%60.%5Cn2.%20Ensure%20there%20are%20no%20pending%20changes%20by%20running%20%60git%20status%60%20and%20creating%20a%20new%20commit%20for%20them%20if%20necessary.%5Cn3.%20Run%20%60npm%20run%20regen-apis%60%20to%20regenerate%20all%20API%20docs%20versions%20for%20%60qiskit%60%2C%20%60qiskit-ibm-runtime%60%2C%20and%20%60qiskit-ibm-transpiler%60.%5Cn%5CnEach%20regenerated%20version%20will%20be%20saved%20as%20a%20distinct%20commit.%20If%20the%20changes%20are%20too%20large%20for%20one%20single%20PR%2C%20consider%20splitting%20it%20up%20into%20multiple%20PRs%20by%20using%20%60git%20cherry-pick%60%20or%20%60git%20rebase%20-i%60%20so%20each%20PR%20only%20has%20the%20commits%20it%20wants%20to%20target.%5Cn%5CnIf%20you%20only%20want%20to%20regenerate%20the%20latest%20stable%20minor%20release%20of%20each%20package%2C%20then%20add%20%60--current-apis-only%60%20as%20an%20argument%2C%20and%20in%20case%20you%20only%20want%20to%20regenerate%20versions%20of%20one%20package%2C%20then%20you%20can%20use%20the%20%60-p%20%3Cpkg-name%3E%60%20argument.%5Cn%5CnAlternatively%2C%20you%20can%20also%20regenerate%20one%20specific%20version%3A%5Cn%5Cn1.%20Choose%20which%20documentation%20you%20want%20to%20generate%20(%60qiskit%60%2C%20%60qiskit-ibm-runtime%60%2C%20or%20%60qiskit-ibm-transpiler%60)%20and%20its%20version.%5Cn2.%20Run%20%60npm%20run%20gen-api%20--%20-p%20%3Cpkg-name%3E%20-v%20%3Cversion%3E%60%2C%5Cn%20%20%20e.g.%20%60npm%20run%20gen-api%20--%20-p%20qiskit%20-v%200.45.0%60%5Cn%5CnIf%20the%20version%20is%20not%20for%20the%20latest%20stable%20minor%20release%20series%2C%20then%20add%20%60--historical%60%20to%20the%20arguments.%20For%20example%2C%20use%20%60--historical%60%20if%20the%20latest%20stable%20release%20is%200.45.%5C%5C*%20but%20you're%20generating%20docs%20for%20the%20patch%20release%200.44.3.%5Cn%5CnAdditionally%2C%20If%20you%20are%20regenerating%20a%20dev%20version%2C%20then%20you%20can%20add%20%60--dev%60%20as%20an%20argument%20and%20the%20documentation%20will%20be%20built%20at%20%60%2Fdocs%2Fapi%2F%3Cpkg-name%3E%2Fdev%60.%20For%20dev%20versions%2C%20end%20the%20%60--version%60%20in%20%60-dev%60%2C%20e.g.%20%60-v%201.0.0-dev%60.%20If%20a%20release%20candidate%20has%20already%20been%20released%2C%20use%20%60-v%201.0.0rc1%60%2C%20for%20example.%5Cn%5CnIn%20this%20case%2C%20no%20commit%20will%20be%20automatically%20created.%5Cn%5Cn%23%23%20Generate%20new%20API%20docs%5Cn%5CnThis%20is%20useful%20when%20new%20docs%20content%20is%20published%2C%20usually%20corresponding%20to%20new%20releases%20or%20hotfixes%20for%20content%20issues.%20If%20you're%20generating%20a%20patch%20release%2C%20also%20see%20the%20below%20subsection%20for%20additional%20steps.%5Cn%5Cn1.%20Choose%20which%20documentation%20you%20want%20to%20generate%20(%60qiskit%60%2C%20%60qiskit-ibm-runtime%60%2C%20or%20%60qiskit-ibm-transpiler%60)%20and%20its%20version.%5Cn2.%20Determine%20the%20full%20version%2C%20such%20as%20by%20looking%20at%20https%3A%2F%2Fgithub.com%2FQiskit%2Fqiskit%2Freleases%5Cn3.%20Download%20a%20CI%20artifact%20with%20the%20project's%20documentation.%20To%20find%20this%3A%5Cn%20%20%201.%20Pull%20up%20the%20CI%20runs%20for%20the%20stable%20commit%20that%20you%20want%20to%20build%20docs%20from.%20This%20should%20not%20be%20from%20a%20Pull%20Request%5Cn%20%20%202.%20Open%20up%20the%20%5C%22Details%5C%22%20for%20the%20relevant%20workflow.%5Cn%20%20%20%20%20%20-%20Qiskit%3A%20%5C%22Documentation%20%2F%20Build%20(push)%5C%22%5Cn%20%20%20%20%20%20-%20Runtime%3A%20%5C%22CI%20%2F%20Build%20documentation%20(push)%5C%22%5Cn%20%20%203.%20Click%20the%20%5C%22Summary%5C%22%20page%20at%20the%20top%20of%20the%20left%20navbar.%5Cn%20%20%204.%20Scroll%20down%20to%20%5C%22Artifacts%5C%22%20and%20look%20for%20the%20artifact%20related%20to%20documentation%2C%20such%20as%20%60html_docs%60.%5Cn%20%20%205.%20Download%20the%20artifact%20by%20clicking%20on%20its%20name.%5Cn4.%20Rename%20the%20downloaded%20zip%20file%20with%20its%20version%20number%2C%20e.g.%20%600.45.zip%60%20for%20an%20artifact%20from%20%60qiskit%20v0.45.2%60.%5Cn5.%20Upload%20the%20renamed%20zip%20file%20to%20https%3A%2F%2Fibm.ent.box.com%2Ffolder%2F246867452622%5Cn6.%20Share%20the%20file%20by%20clicking%20the%20%60Copy%20shared%20link%60%20button%5Cn7.%20Select%20%60People%20with%20the%20link%60%20and%20go%20to%20%60Link%20Settings%60.%5Cn8.%20Under%20%60Link%20Expiration%60%20select%20%60Disable%20Shared%20Link%20on%60%20and%20set%20an%20expiration%20date%20of%20~10%20years%20into%20the%20future.%5Cn9.%20Copy%20the%20direct%20link%20at%20the%20end%20of%20the%20%60Shared%20Link%20Settings%60%20tab.%5Cn10.%20Modify%20the%20%60scripts%2Fconfig%2Fapi-html-artifacts.json%60%20file%2C%20adding%20the%20new%20versions%20with%20the%20direct%20link%20from%20step%209.%5Cn11.%20Run%20%60npm%20run%20gen-api%20--%20-p%20%3Cpkg-name%3E%20-v%20%3Cversion%3E%60%2C%5Cn%20%20%20%20e.g.%20%60npm%20run%20gen-api%20--%20-p%20qiskit%20-v%200.45.0%60%5Cn%5CnIf%20you%20are%20regenerating%20a%20dev%20version%2C%20then%20you%20can%20add%20%60--dev%60%20as%20an%20argument%20and%20the%20documentation%20will%20be%20built%20at%20%60%2Fdocs%2Fapi%2F%3Cpkg-name%3E%2Fdev%60.%20For%20dev%20versions%2C%20end%20the%20%60--version%60%20in%20%60-dev%60%2C%20e.g.%20%60-v%201.0.0-dev%60.%20If%20a%20release%20candidate%20has%20already%20been%20released%2C%20use%20%60-v%201.0.0rc1%60%2C%20for%20example.%5Cn%5CnIn%20case%20you%20want%20to%20save%20the%20current%20version%20and%20convert%20it%20into%20a%20historical%20one%2C%20you%20can%20run%20%60npm%20run%20make-historical%20--%20-p%20%3Cpkg-name%3E%60%20beforehand.%5Cn%5Cn%23%23%23%20Generate%20patch%20releases%5Cn%5CnFor%20example%2C%20if%20the%20current%20docs%20are%20for%200.45.2%20but%20you%20want%20to%20generate%200.45.3.%5Cn%5CnFollow%20the%20same%20process%20above%20for%20new%20API%20docs%2C%20other%20than%3A%5Cn%5Cn-%20When%20uploading%20the%20artifact%2C%20overwrite%20the%20existing%20file%20with%20the%20new%20one.%20Be%20careful%20to%20follow%20the%20above%20steps%20to%20change%20%5C%22Link%20Expiration%5C%22!%5Cn%5CnIf%20the%20version%20is%20not%20for%20the%20latest%20stable%20minor%20release%20series%2C%20then%20add%20%60--historical%60%20to%20the%20arguments.%20For%20example%2C%20use%20%60--historical%60%20if%20the%20latest%20stable%20release%20is%200.45.%5C%5C*%20but%20you're%20generating%20docs%20for%20the%20patch%20release%200.44.3.%5Cn%5Cn%23%23%23%20View%20diff%20for%20%60objects.inv%60%5Cn%5CnSince%20%60objects.inv%60%20is%20compressed%2C%20we%20can't%20review%20changes%20through%20%60git%20diff%60.%20Git%20_does_%20tell%20you%20if%20the%20file%20has%20changed%2C%20but%20this%20isn't%20that%20helpful%20as%20the%20compressed%20file%20can%20be%20different%20even%20if%20the%20uncompressed%20contents%20are%20the%20same.%5CnIf%20you%20want%20to%20see%20the%20diff%20for%20the%20uncompressed%20contents%2C%20first%20install%20%5B%60sphobjinv%60%5D(https%3A%2F%2Fgithub.com%2Fbskinn%2Fsphobjinv).%5Cn%5Cn%60%60%60sh%5Cnpipx%20install%20sphobjinv%5Cn%60%60%60%5Cn%5CnThe%20add%20the%20following%20to%20your%20%60.gitconfig%60%20(usually%20found%20at%20%60~%2F.gitconfig%60).%5Cn%5Cn%60%60%60%5Cn%5Bdiff%20%5C%22objects_inv%5C%22%5D%5Cn%20%20textconv%20%3D%20sh%20-c%20'sphobjinv%20convert%20plain%20%5C%22%240%5C%22%20-'%5Cn%60%60%60%5Cn%5Cn%23%23%23%20Dependabot%20-%20upgrade%20notebook%20testing%20version%5Cn%5CnWhen%20a%20new%20version%20of%20an%20API%20is%20released%2C%20we%20should%20also%20update%20%60nb-tester%2Frequirements.txt%60%20to%20ensure%20that%20our%20notebooks%20still%20work%20with%20the%20latest%20version%20of%20the%20API.%20You%20can%20do%20this%20upgrade%20either%20manually%20or%20wait%20for%20Dependabot's%20automated%20PR.%5Cn%5CnDependabot%20will%20fail%20to%20run%20at%20first%20due%20to%20not%20having%20access%20to%20the%20token.%20To%20fix%20this%2C%20have%20someone%20with%20write%20access%20trigger%20CI%20for%20the%20PR%2C%20such%20as%20by%20merging%20main%20or%20closing%20then%20reopening%20the%20issue.%5Cn%5CnYou%20can%20land%20the%20API%20generation%20separately%20from%20the%20%60requirements.txt%60%20version%20upgrade.%20It's%20high%20priority%20to%20get%20out%20new%20versions%20of%20the%20API%20docs%20ASAP%2C%20so%20you%20should%20not%20block%20that%20on%20the%20notebook%20version%20upgrade%20if%20you%20run%20into%20any%20complications%20like%20failing%20notebooks.%5Cn%5Cn%23%23%20Deploy%20guides%20%26%20API%20docs%5Cn%5CnSee%20the%20section%20%5C%22Syncing%20content%20with%20open%20source%20repo%5C%22%20in%20the%20internal%20docs%20repo's%20README.%5Cn%5Cn%23%20How%20to%20write%20the%20documentation%5Cn%5CnRefer%20to%20our%20%5Bstyle%20guide%5D(.%2Fstyle-guide.md)%20for%20technical%20writing%20guidance.%5Cn%5CnWe%20use%20%5BMDX%5D(https%3A%2F%2Fmdxjs.com)%2C%20which%20is%20like%20normal%20markdown%20but%20adds%20extensions%20for%20custom%20components%20we%20have.%5Cn%5CnRefer%20to%20the%20%5BCommon%20Markdown%20syntax%5D(https%3A%2F%2Fcommonmark.org%2F)%20for%20a%20primer%20on%20Markdown.%20The%20below%20guide%20focuses%20on%20the%20other%20features%20you%20can%20use%20when%20writing%20docs.%5Cn%5Cn%23%23%20How%20to%20add%20a%20new%20page%5Cn%5CnChoose%20which%20existing%20folder%20from%20%60docs%2F%60%20your%20new%20page%20belongs%20to%20(probably%20%60guides%60).%5Cn%5CnNext%2C%20choose%20the%20file%20name.%20The%20file%20name%20will%20determine%20the%20URL.%20For%20example%2C%20%60start%2Fmy-new-page.mdx%60%20results%20in%20the%20URL%20%60start%2Fmy-new-page%60.%20Choose%20a%20file%20name%20that%20will%20be%20stable%20over%20the%20page's%20lifespan%20and%20that%20is%20unlikely%20to%20clash%20with%20other%20topics.%20Use%20%60-%60%20rather%20than%20%60_%60%20as%20the%20delimiter.%20You%20can%20also%20ask%20for%20help%20choosing%20a%20name%20in%20the%20GitHub%20issue%20or%20pull%20request.%5Cn%5CnIf%20your%20file%20will%20have%20non-trivial%20code%20in%20it%2C%20please%20create%20a%20Jupyter%20notebook%20ending%20in%20%60.ipynb%60%2C%20rather%20than%20an%20MDX%20file.%20We%20prefer%20Jupyter%20notebooks%20when%20there%20is%20code%20because%20we%20have%20tests%20to%20make%20sure%20that%20the%20code%20still%20executes%20properly%2C%20whereas%20MDX%20is%20not%20tested.%5Cn%5CnAdd%20the%20file%20to%20these%20places%3A%5Cn%5Cn-%20The%20folder's%20%60_toc.json%60%2C%20such%20as%20%60guides%2F_toc.json%60.%20The%20%60title%60%20will%20show%20up%20in%20the%20left%20side%20bar.%20Note%20that%20the%20%60url%60%20leaves%20off%20the%20file%20extension.%5Cn-%20The%20appropriate%20%5C%22index%5C%22%20page%20in%20the%20Development%20workflow%20section%2C%20such%20as%20%60guides%2Fmap-problem-to-circuits%60%20AND%20the%20Tools%20section%20in%20the%20%60_toc.json%60%20file.%20Or%2C%20in%20the%20rare%20case%20that%20it%20doesn't%20belong%20on%20any%20of%20these%20pages%2C%20list%20it%20in%20%60scripts%2Fjs%2Fcommands%2FcheckPatternsIndex.ts%60%20in%20the%20ALLOWLIST_MISSING_FROM_INDEX%20or%20the%20ALLOWLIST_MISSING_FROM_TOC%20section.%20For%20example%2C%20%60%5C%22%2Fguides%2Fqiskit-code-assistant%5C%22%60.%5Cn-%20qiskit_bot.yaml.%20Everyone%20listed%20under%20the%20file%20name%20is%20notified%20any%20time%20the%20file%20is%20updated.%20If%20someone%20wants%20to%20be%20listed%20as%20an%20owner%20but%20does%20not%20want%20to%20receive%20notifications%2C%20put%20their%20ID%20in%20single%20quotes.%20For%20example%2C%20-%20%5C%22%60%40NoNotifications%60%5C%22%5Cn%5Cn%23%23%20Page%20metadata%5Cn%5CnEvery%20page%20must%20set%20a%20%60title%60%20and%20%60description%60%3A%5Cn%5Cn-%20The%20title%20is%20used%20for%20browser%20tabs%20and%20the%20top%20line%20of%20search%20results.%20It%20should%20usually%20match%20the%20title%20used%20in%20the%20%60_toc.json%60%20file.%5Cn-%20The%20description%20should%20describe%20the%20page%20in%20at%20least%2050%20but%20no%20more%20than%20160%20characters%2C%20ideally%20using%20some%20keywords.%20The%20description%20is%20what%20shows%20up%20as%20the%20text%20in%20search%20results.%20See%20https%3A%2F%2Fgithub.com%2FQiskit%2Fdocumentation%2Fissues%2F131%20for%20some%20tips.%5Cn%5CnIn%20MDX%20files%2C%20set%20the%20metadata%20at%20the%20top%20of%20the%20file%20like%20this%3A%5Cn%5Cn%60%60%60%5Cn---%5Cntitle%3A%20Representing%20quantum%20computers%5Cndescription%3A%20Learn%20about%20coupling%20maps%2C%20basis%20gates%2C%20and%20backend%20errors%20for%20transpiling%5Cn---%5Cn%60%60%60%5Cn%5CnIn%20Jupyter%20notebooks%2C%20set%20%60title%60%20and%20%60description%60%20in%20the%20%60metadata%60%20section%20for%20the%20file.%20In%20VSCode%2C%20you%20can%20set%20up%20the%20metadata%20with%20these%20instructions%3A%5Cn%5Cn1.%20Open%20up%20the%20file%20with%20the%20%5C%22Open%20With...%5C%22%20option%20(one%20way%20to%20do%20this%20is%20to%20right-click%20the%20file%20name%20to%20find%20the%20%5C%22Open%20With...%5C%22%20option)%20and%20then%20%5C%22Text%20Editor%5C%22.%5Cn2.%20Scroll%20down%20to%20the%20bottom%20of%20the%20file%20for%20the%20top-level%20key%20%5C%22metadata%5C%22.%20Ensure%20that%20this%20is%20the%20metadata%20for%20the%20entire%20file%20and%20not%20for%20a%20single%20code%20block.%20You%20should%20see%20in%20the%20%5C%22metadata%5C%22%20section%20other%20entries%20like%20%5C%22language_info%5C%22%20and%20%5C%22nbconvert_exporter%5C%22.%5Cn3.%20Add%20new%20keys%20in%20the%20%5C%22metadata%5C%22%20section%20for%20%5C%22title%5C%22%20and%20%5C%22description%5C%22.%5Cn%5Cn%60%60%60json%5Cn%5C%22metadata%5C%22%3A%20%7B%5Cn%20%20%5C%22description%5C%22%3A%20%5C%22Get%20started%20using%20Qiskit%20with%20IBM%20Quantum%20hardware%20in%20this%20Hello%20World%20example%5C%22%2C%5Cn%20%20%5C%22title%5C%22%3A%20%5C%22Hello%20world%5C%22%2C%5Cn%20%20%5C%22celltoolbar%5C%22%3A%20%5C%22Raw%20Cell%20Format%5C%22%2C%5Cn%20%20%5C%22kernelspec%5C%22%3A%20%7B%20...%5Cn%7D%5Cn%60%60%60%5Cn%5Cn%23%23%20Links%5Cn%5CnInternal%20URLs%20referring%20to%20other%20docs%20pages%20should%20start%20with%20%60%2F%60%20and%20not%20include%20the%20file%20extension.%20For%20example%3A%5Cn%5Cn-%20%60%5BQiskit%20SDK%5D(%2Fapi%2Fqiskit)%60%5Cn-%20%60%5BBit%20ordering%20in%20the%20Qiskit%20SDK%5D(%2Fguides%2Fbit-ordering)%60%5Cn%5CnExternal%20URLs%20should%20use%20the%20entire%20URL%2C%20such%20as%20%60%5BGitHub%5D(https%3A%2F%2Fgithub.com)%60.%5Cn%5Cn%23%23%20Images%5Cn%5CnImages%20are%20stored%20in%20the%20%60public%2Fimages%60%20folder.%20You%20should%20use%20subfolders%20to%20organize%20the%20files.%20For%20example%2C%20images%20for%20%60guides%2Fmy-file.mdx%60%20should%20be%20stored%20like%20%60public%2Fimages%2Fguides%2Fmy-file%2Fimg1.png%60.%5Cn%5CnTo%20use%20the%20image%3A%5Cn%5Cn%60%60%60markdown%5Cn!%5BAlt%20text%20for%20the%20image%5D(%2Fimages%2Fguides%2Fyour-file%2Fyour_image.png)%5Cn%60%60%60%5Cn%5CnTo%20add%20an%20inline%20images%3A%5Cn%5Cn%60%60%60markdown%5CnInline%20!%5BAlt%20text%20for%20the%20image%5D(%2Fimages%2Fguides%2Fyour-file%2Fyour_image.png)%20image%5Cn%60%60%60%5Cn%5CnTo%20include%20a%20caption%3A%5Cn%5Cn%60%60%60markdown%5Cn!%5BAlt%20text%20for%20the%20image%5D(%2Fimages%2Fguides%2Fyour-file%2Fyour_image.png%20%5C%22Image%20caption%5C%22)%5Cn%60%60%60%5Cn%5CnYou%20can%20include%20a%20version%20of%20the%20image%20to%20be%20with%20the%20dark%20theme.%20You%20only%20need%20to%20create%20an%20image%20with%20the%20same%20name%20ending%20in%20%60%40dark%60.%20So%20for%20example%2C%20if%20you%20have%20a%20%60sampler.png%60%20image%2C%20the%20dark%20version%20would%20be%20%60sampler%40dark.png%60.%20This%20is%20important%20for%20images%20that%20have%20a%20white%20background.%5Cn%5Cn%23%23%20Videos%5Cn%5CnVideos%20are%20stored%20in%20the%20%60public%2Fvideos%60%20folder.%20You%20should%20use%20subfolders%20to%20organize%20the%20files.%20For%20example%2C%20images%20for%20%60guides%2Fmy-file.mdx%60%20should%20be%20stored%20like%20%60public%2Fvideos%2Fguides%2Fmy-file%2Fvideo1.mp4%60.%5Cn%5CnTo%20add%20a%20video%3A%5Cn%5Cn%60%60%60markdown%5Cn%3Cvideo%20title%3D%5C%22Write%20a%20description%20of%20the%20video%20here%20as%20'alt%20text'%20for%20accessibility.%5C%22%20className%3D%5C%22max-w-auto%20h-auto%5C%22%20controls%3E%5Cn%20%20%20%20%3Csource%20src%3D%5C%22%2Fvideos%2Fguides%2Fsessions%2Fdemo.mp4%5C%22%20type%3D%5C%22video%2Fmp4%5C%22%3E%3C%2Fsource%3E%5Cn%3C%2Fvideo%3E%5Cn%60%60%60%5Cn%5Cn%23%23%20Math%5Cn%5CnWe%20use%20%5BLaTeX%5D(https%3A%2F%2Fwww.latex-project.org)%20to%20write%20math%2C%20which%20gets%20rendered%20by%20the%20library%20%5BKaTeX%5D(https%3A%2F%2Fkatex.org).%5Cn%5CnInline%20math%20expressions%20should%20start%20with%20%60%24%60%20and%20end%20with%20%60%24%60%2C%20e.g.%20%60%24%5C%5Cfrac%7B123%7D%7B2%7D%24%60.%5Cn%5CnMulti-line%20expressions%20should%20start%20with%20%60%24%24%60%20and%20end%20with%20%60%24%24%60%3A%5Cn%5Cn%60%60%60markdown%5Cn%24%24%5CnL%20%3D%20%5C%5Cfrac%7B123%7D%7B2%7D%20%5C%5Crho%20v%5E2%20S%20C_1s%5Cn%24%24%5Cn%60%60%60%5Cn%5Cn%23%23%20Tables%5Cn%5CnTables%20are%20supported%3A%20https%3A%2F%2Fwww.markdownguide.org%2Fextended-syntax%2F.%5Cn%5Cn%23%23%20Comments%5Cn%5CnExample%20comment%3A%20%60%7B%2F*%20Comes%20from%20https%3A%2F%2Fqiskit.org%2Fdocumentation%2Fpartners%2Fqiskit_ibm_runtime%2Fgetting_started.html%20*%2F%7D%60%5Cn%5Cn%23%23%20Collapsible%20sections%5Cn%5CnFor%20content%20that%20you%20don't%20want%20to%20show%20by%20default%2C%20use%20a%20collapsible%20section.%20The%20user%20will%20need%20to%20expand%20the%20section%20to%20read%20its%20contents.%20Refer%20to%20GitHub's%20guide%20on%20%5B%60%3Cdetails%3E%60%20and%20%60%3Csummary%3E%60%5D(https%3A%2F%2Fdocs.github.com%2Fen%2Fget-started%2Fwriting-on-github%2Fworking-with-advanced-formatting%2Forganizing-information-with-collapsed-sections).%5Cn%5Cn%23%23%20Footnotes%5Cn%5Cn%60%60%60%5CnFootnote%201%20link%5B%5Efirst%5D.%5Cn%5CnFootnote%202%20link%5B%5Esecond%5D.%5Cn%5CnDuplicated%20footnote%20reference%5B%5Esecond%5D.%5Cn%5Cn%5B%5Efirst%5D%3A%20Footnote%20**can%20have%20markup**%5Cn%5Cn%20%20%20%20and%20multiple%20paragraphs.%5Cn%5Cn%5B%5Esecond%5D%3A%20Second%20footnote%20text.%5Cn%60%60%60%5Cn%5Cn%23%23%20Custom%20components%5Cn%5CnThese%20are%20components%20that%20we%20expose%20through%20MDX.%20You%20can%20use%20them%20in%20both%5Cn%60.mdx%60%20and%20%60.ipynb%60%20files.%20In%20Jupyter%20notebooks%2C%20use%20Markdown%20cells.%5Cn%5Cn%23%23%23%20Admonitions%5Cn%5CnTo%20use%20an%20%60Admonition%60%2C%20use%20the%20following%20syntax%5Cn%5Cn%60%60%60mdx%5Cn%3CAdmonition%20type%3D%5C%22note%5C%22%3EThis%20is%20an%20example%20of%20a%20note.%3C%2FAdmonition%3E%5Cn%60%60%60%5Cn%5CnAvailable%20types%20are%20%60note%2C%20tip%2C%20info%2C%20caution%2C%20danger%60.%20This%20is%20what%20they%20look%20like%3A%5Cn%5Cn!%5Btypes%5D(https%3A%2F%2Fgithub.com%2FQiskit%2Fdocumentation%2Fassets%2F66339736%2F9911d171-2dbb-45a2-af84-6502d5fc0ae0)%5Cn%5CnBy%20default%2C%20the%20title%20is%20the%20%60type%60%20capitalized.%20You%20can%20customize%20it%20by%20setting%20%60title%60%3A%5Cn%5Cn%60%60%60mdx%5Cn%3CAdmonition%20type%3D%5C%22note%5C%22%20title%3D%5C%22Custom%20title%5C%22%3E%5Cn%20%20This%20is%20a%20__note__%20example%5Cn%3C%2FAdmonition%3E%5Cn%60%60%60%5Cn%5Cn%23%23%23%20Definition%20Tooltip%5Cn%5CnTo%20use%20a%20%60DefinitionTooltip%60%2C%20use%20the%20following%20syntax%3A%5Cn%5Cn%60%60%60mdx%5Cn%3CDefinitionTooltip%20definition%3D%5C%22Definition%20for%20the%20Term%5C%22%3ETerm%3C%2FDefinitionTooltip%3E%5Cn%60%60%60%5Cn%5CnFor%20full%20list%20of%20props%2C%20please%20check%20%5Bhere%5D(https%3A%2F%2Freact.carbondesignsystem.com%2F%3Fpath%3D%2Fdocs%2Fcomponents-definitiontooltip--playground%23component-api).%5Cn%5Cn%23%23%23%20Tabs%5Cn%5CnTo%20use%20a%20%60Tabs%60%20component%2C%20use%20the%20following%20syntax%3A%5Cn%5Cn%60%60%60mdx%5Cn%3CTabs%3E%5Cn%20%20%3CTabItem%20value%3D%5C%22pulses%5C%22%20label%3D%5C%22Pulses%5C%22%3E%5Cn%20%20%20%20This%20is%20the%20text%20for%20pulses%5Cn%20%20%3C%2FTabItem%3E%5Cn%5Cn%20%20%3CTabItem%20value%3D%5C%22qasm%5C%22%20label%3D%5C%22QASM%5C%22%3E%5Cn%20%20%20%20This%20is%20the%20text%20for%20QASM%5Cn%20%20%3C%2FTabItem%3E%5Cn%3C%2FTabs%3E%5Cn%60%60%60%5Cn%5CnBy%20default%2C%20the%20first%20tab%20is%20selected.%20You%20can%20change%20that%20by%20using%20the%20%60defaultValue%60%20prop.%5Cn%5Cn%60%60%60mdx%5Cn%3CTabs%20defaultValue%3D%5C%22qasm%5C%22%3E%5Cn%20%20%3CTabItem%20value%3D%5C%22pulses%5C%22%20label%3D%5C%22Pulses%5C%22%3E%5Cn%20%20%20%20This%20is%20the%20text%20for%20pulses%5Cn%20%20%3C%2FTabItem%3E%5Cn%5Cn%20%20%3CTabItem%20value%3D%5C%22qasm%5C%22%20label%3D%5C%22QASM%5C%22%3E%5Cn%20%20%20%20This%20is%20the%20text%20for%20QASM%5Cn%20%20%3C%2FTabItem%3E%5Cn%3C%2FTabs%3E%5Cn%60%60%60%5Cn%5CnThere%20are%20situations%20where%20you%20want%20to%20repeat%20the%20same%20tabs%20in%20several%20part%20of%20the%20page.%20In%20this%20situation%2C%20you%20can%20use%20the%20prop%20%60group%60%20to%20synchronize%20the%20selected%20tab%20in%20all%20usages.%5Cn%5Cn%60%60%60mdx%5Cn%3CTabs%20group%3D%5C%22my-group%5C%22%3E%5Cn%20%20%3CTabItem%20value%3D%5C%22pulses%5C%22%20label%3D%5C%22Pulses%5C%22%3E%5Cn%20%20%20%20This%20is%20the%20text%20for%20pulses%5Cn%20%20%3C%2FTabItem%3E%5Cn%5Cn%20%20%3CTabItem%20value%3D%5C%22qasm%5C%22%20label%3D%5C%22QASM%5C%22%3E%5Cn%20%20%20%20This%20is%20the%20text%20for%20QASM%5Cn%20%20%3C%2FTabItem%3E%5Cn%3C%2FTabs%3E%5Cn%60%60%60%5Cn%5CnThere%20is%20a%20specific%20use%20case%20where%20you%20want%20to%20show%20instructions%20for%20different%20operating%20systems.%20In%20this%20situation%2C%20you%20can%20replace%20the%20%60Tabs%60%20component%20by%20a%20%60OperatingSystemTabs%60.%20The%20default%20value%20of%20the%20tab%20will%20be%20selected%20based%20on%20the%20user's%20operating%20system.%5Cn%5Cn%60%60%60mdx%5Cn%3COperatingSystemTabs%3E%5Cn%20%20%3CTabItem%20value%3D%5C%22mac%5C%22%20label%3D%5C%22macOS%5C%22%3E%5Cn%20%20%20%20Open%20a%20terminal%20and%20write%20the%20command%5Cn%20%20%3C%2FTabItem%3E%5Cn%20%20%3CTabItem%20value%3D%5C%22linux%5C%22%20label%3D%5C%22Linux%5C%22%3E%5Cn%20%20%20%20Open%20a%20terminal%20and%20write%20the%20command%5Cn%20%20%3C%2FTabItem%3E%5Cn%20%20%3CTabItem%20value%3D%5C%22win%5C%22%20label%3D%5C%22Windows%5C%22%3E%5Cn%20%20%20%20Go%20to%20windows%2Frun%20and%20write%20%60cmd%60.%20It%20will%20open%20a%20command%20line.%20Execute%20this%5Cn%20%20%20%20command%5Cn%20%20%3C%2FTabItem%3E%5Cn%3C%2FOperatingSystemTabs%3E%5Cn%60%60%60%5Cn%5Cn%23%23%20Proper%20marking%20and%20attribution%5Cn%5Cn**All%20information%20needs%20to%20identify%2C%20mark%2C%20and%20attribute%20IBM%20and%20applicable%20third-party%20trademarks.**%20We%20do%20this%20the%20first%20time%20an%20IBM%20trademark%20appears%20on%20each%20page.%20See%20the%20%5BCopyright%20and%20trademark%20information%5D(https%3A%2F%2Fwww.ibm.com%2Flegal%2Fcopyright-trademark)%20page%20for%20more%20details.%5Cn%5CnSome%20companies%20require%20a%20special%20attribution%20notice.%20View%20a%20list%20of%20the%20companies%20to%20include%20in%20a%20special%20attribution%20notice%20at%20the%20%5BSpecial%20attributions%5D(https%3A%2F%2Fwww.ibm.com%2Flegal%2Fcopyright-trademark%23special)%20section%20of%20the%20IBM%20Legal%20site.%5Cn%5Cn%3Cdetails%3E%5Cn%3Csummary%3EA%20(non-exhaustive)%20list%20of%20trademarked%20names%20found%20in%20our%20docs%3A%3C%2Fsummary%3E%5Cn%5Cn-%20IBM%26reg%3B%5Cn-%20IBM%20Cloud%26reg%3B%5Cn-%20IBM%20Quantum%26trade%3B%5Cn%3C%2Fdetails%3E%5Cn%5Cn**Note**%3A%20Although%20Qiskit%20is%20a%20registered%20trademark%20of%20IBM%2C%20we%20do%20not%20mark%20it%20as%20such.%5Cn%5CnSee%20the%20Usage%20section%20of%20the%20IBM%20Quantum%20Experience%20Guide%20for%20guidance%20on%20when%20to%20use%20IBM%20and%20when%20to%20use%20IBM%20Quantum.%5Cn%5Cn%23%23%23%20Trademark%20symbols%5Cn%5CnTo%20create%20the%20symbols%20in%20markdown%3A%5Cn%5CnUse%20%60%26reg%3B%60%20to%20get%20%26reg%3B%20for%20registered%20trademarks.%5Cn%5Cnuse%20%60%26trade%3B%60%20to%20get%20%26trade%3B%20for%20nonregistered%20trademarks.%5Cn%5Cn%E2%9A%A0%EF%B8%8F%20**Note**%3A%20Do%20not%20include%20trademarks%20in%20headings.%20The%20code%20will%20display%20rather%20than%20the%20symbol.%5Cn%22%2C%22sha%22%3A%220c68aa36571a369251fc8e5016d074609a0ae29a%22%2C%22replace_content%22%3A%22%23%20Qiskit%20documentation%5Cn%5CnThe%20documentation%20content%20home%20for%20https%3A%2F%2Fdocs.quantum.ibm.com%20(excluding%20API%20reference).%5Cn%5Cn%23%20Improving%20IBM%20Quantum%20%26%20Qiskit%20Documentation%5Cn%5CnMaintaining%20up-to-date%20documentation%20is%20a%20huge%20challenge%20for%20any%20software%20project%2C%20especially%20in%20a%20field%20like%20quantum%20computing%20where%20the%20pace%20at%20which%20advances%20in%20new%20research%20and%20technological%20capabilities%20happen%20incredibly%20fast.%20As%20a%20result%2C%20we%20greatly%20appreciate%20any%20who%20take%20the%20time%20to%20support%20us%20in%20keeping%20this%20content%20accurate%20and%20up%20to%20the%20highest%20quality%20standard%20possible%20to%20benefit%20the%20broadest%20range%20of%20users.%5Cn%5CnRead%20on%20for%20more%20information%20about%20how%20to%20support%20this%20project%3A%5Cn%5Cn%23%23%20Best%20ways%20to%20contribute%20to%20Documentation%5Cn%5Cn%23%23%23%201.%20Report%20bugs%2C%20inaccuracies%20or%20general%20content%20issues%5Cn%5CnThis%20is%20the%20quickest%2C%20easiest%2C%20and%20most%20helpful%20way%20to%20contribute%20to%20this%20project%20and%20improve%20the%20quality%20of%20Qiskit%26reg%3B%20and%20IBM%20Quantum%26trade%3B%20documentation.%20There%20are%20a%20few%20different%20ways%20to%20report%20issues%2C%20depending%20on%20where%20it%20was%20found%3A%5Cn%5Cn-%20For%20problems%20you've%20found%20in%20the%20%5BQiskit%20SDK%20API%20Reference%5D(https%3A%2F%2Fdocs.quantum.ibm.com%2Fapi%2Fqiskit)%20section%2C%20open%20an%20issue%20in%20the%20Qiskit%20repo%20%5Bhere%5D(https%3A%2F%2Fgithub.com%2FQiskit%2Fqiskit%2Fissues%2Fnew%2Fchoose).%5Cn-%20For%20problems%20you've%20found%20in%20the%20%5BQiskit%20Runtime%20Client%5D(https%3A%2F%2Fdocs.quantum.ibm.com%2Fapi%2Fqiskit-ibm-runtime)%20section%2C%20open%20an%20issue%20in%20the%20Qiskit%20IBM%20Runtime%20repo%20%5Bhere%5D(https%3A%2F%2Fgithub.com%2FQiskit%2Fqiskit-ibm-runtime%2Fissues%2Fnew%2Fchoose).%5Cn-%20For%20problems%20you've%20found%20in%20any%20other%20section%20of%20%5Bdocs%5D(https%3A%2F%2Fdocs.quantum.ibm.com)%2C%20open%20a%20content%20bug%20issue%20%5Bhere%5D(https%3A%2F%2Fgithub.com%2FQiskit%2Fdocumentation%2Fissues%2Fnew%2Fchoose).%5Cn%5Cn%23%23%23%202.%20Suggest%20new%20content%5Cn%5CnIf%20you%20think%20there%20are%20gaps%20in%20our%20documentation%2C%20or%20sections%20that%20could%20be%20expanded%20upon%2C%20we%20invite%20you%20to%20open%20a%20new%20content%20request%20issue%20%5Bhere%5D(https%3A%2F%2Fgithub.com%2FQiskit%2Fdocumentation%2Fissues%2Fnew%2Fchoose).%5Cn%5CnNot%20every%20new%20content%20suggestion%20is%20a%20good%20fit%20for%20docs%2C%20nor%20are%20we%20able%20to%20prioritize%20every%20request%20immediately.%20However%2C%20we%20will%20do%20our%20best%20to%20respond%20to%20content%20requests%20in%20a%20timely%20manner%2C%20and%20we%20greatly%20appreciate%20our%20community's%20efforts%20in%20generating%20new%20ideas.%5Cn%5CnIf%20you%20are%20interested%20in%20writing%20the%20new%20content%20yourself%2C%20or%20already%20have%20some%20draft%20work%20you%20think%20could%20be%20integrated%2C%20please%20also%20mention%20that%20in%20the%20issue%20description.%20If%20your%20content%20suggestion%20is%20accepted%2C%20we%20will%20let%20you%20know%20and%20work%20with%20you%20to%20get%20the%20content%20written%20and%20reviewed.%5Cn%5CnPlease%20note%3A%20we%20DO%20NOT%20accept%20unsolicited%20PRs%20for%20new%20pages%20or%20large%20updates%20to%20existing%20content.%20The%20content%20that%20we%20include%20in%20docs%20is%20carefully%20planned%20and%20curated%20by%20our%20content%20team%20and%20must%20go%20through%20the%20appropriate%20review%20process%20to%20ensure%20the%20quality%20is%20of%20the%20highest%20possible%20standard%20before%20deploying%20to%20production.%20As%20a%20result%20we%20are%20very%20selective%20with%20which%20content%20suggestions%20are%20approved%2C%20and%20it%20is%20unlikely%20that%20PRs%20submitted%20without%20an%20associated%20approved%20content%20request%20will%20be%20accepted.%5Cn%5Cn%23%23%23%203.%20Validate%20existing%20issues%5Cn%5CnYou%20can%20help%20the%20team%20prioritize%20already-open%20issues%20by%20doing%20the%20following%3A%5Cn%5Cn-%20For%20bug%20reports%2C%20leave%20a%20comment%20in%20the%20issue%20if%20you%20have%20also%20been%20experiencing%20the%20same%20problem%20and%20can%20reproduce%20it%20(include%20as%20much%20information%20as%20you%20can%2C%20e.g.%2C%20browser%20type%2C%20Qiskit%20version%2C%20etc.).%5Cn-%20For%20new%20content%20requests%2C%20leave%20a%20comment%20or%20upvote%20(%F0%9F%91%8D)%20in%20the%20issue%20if%20you%20also%20would%20like%20to%20see%20that%20new%20content%20added.%5Cn%5Cn%23%23%23%204.%20Fix%20an%20open%20issue%5Cn%5CnYou%20can%20look%20through%20the%20open%20issues%20we%20have%20in%20this%20repo%20and%20address%20them%20with%20a%20PR.%20We%20recommend%20focusing%20on%20issues%20with%20the%20%5C%22good%20first%20issue%5C%22%20label.%5Cn%5CnBefore%20getting%20started%20on%20an%20issue%2C%20remember%20to%20do%20the%20following%3A%5Cn%5Cn1.%20Read%20the%20%5BCode%20of%20Conduct%5D(https%3A%2F%2Fdocs.quantum.ibm.com%2Fopen-source%2Fcode-of-conduct)%5Cn2.%20Check%20for%20open%2C%20unassigned%20issues%20with%20the%20%5C%22good%20first%20issue%5C%22%20label%5Cn3.%20Select%20an%20issue%20that%20is%20not%20already%20assigned%20to%20someone%20and%20leave%20a%20comment%20to%20request%20to%20be%20assigned%5Cn%5CnOnce%20you%20have%20an%20issue%20to%20work%20on%2C%20see%20the%20%5C%22How%20to%20work%20with%20this%20repo%5C%22%20section%20below%20to%20get%20going%2C%20then%20open%20a%20PR.%5Cn%5CnBefore%20opening%20a%20PR%2C%20remember%20to%20do%20the%20following%3A%5Cn%5Cn1.%20Check%20that%20you%20have%20addressed%20all%20the%20requirements%20from%20the%20original%20issue%5Cn2.%20Run%20the%20quality%20control%20checks%20with%20%60npm%20run%20check%60%5Cn3.%20Use%20the%20GitHub%20%5C%22fixes%5C%22%20notation%20to%20%5Blink%20your%20PR%20to%20the%20issue%5D(https%3A%2F%2Fdocs.github.com%2Fen%2Fissues%2Ftracking-your-work-with-issues%2Flinking-a-pull-request-to-an-issue)%20you%20are%20addressing%5Cn%5Cn%23%20How%20to%20work%20with%20this%20repo%5Cn%5Cn%23%23%20Prerequisites%20to%20building%20the%20docs%20locally%5Cn%5CnThese%20tools%20will%20also%20run%20in%20CI%2C%20but%20it%20can%20be%20convenient%20when%20iterating%20to%20run%20the%20tools%20locally.%5Cn%5CnFirst%2C%20install%20the%20below%20software%3A%5Cn%5Cn1.%20%5BNode.js%5D(https%3A%2F%2Fnodejs.org%2Fen).%20If%20you%20expect%20to%20use%20JavaScript%20in%20other%20projects%2C%20consider%20using%20%5BNVM%5D(https%3A%2F%2Fgithub.com%2Fnvm-sh%2Fnvm).%20Otherwise%2C%20consider%20using%20%5BHomebrew%5D(https%3A%2F%2Fformulae.brew.sh%2Fformula%2Fnode)%20or%20installing%20%5BNode.js%20directly%5D(https%3A%2F%2Fnodejs.org%2Fen).%5Cn2.%20%5BDocker%5D(https%3A%2F%2Fwww.docker.com).%20You%20must%20also%20ensure%20that%20it%20is%20running.%5Cn%20%20%20-%20If%20you%20cannot%20use%20Docker%20from%20docker.com%2C%20consider%20using%20use%20%5BColima%5D(https%3A%2F%2Fgithub.com%2Fabiosoft%2Fcolima)%20or%20%5BRancher%20Desktop%5D(https%3A%2F%2Francherdesktop.io).%20When%20installing%20Rancher%20Desktop%2C%20choose%20Moby%2FDockerd%20as%20the%20engine%2C%20rather%20than%20nerdctl.%20To%20ensure%20it's%20running%2C%20open%20up%20the%20app%20%5C%22Rancher%20Desktop%5C%22.%5Cn%5CnThen%2C%20install%20the%20dependencies%20with%3A%5Cn%5Cn%60%60%60bash%5Cnnpm%20install%5Cn%60%60%60%5Cn%5Cn%23%23%20Preview%20the%20docs%20locally%5Cn%5CnYou%20can%20preview%20the%20docs%20locally%20by%20following%20these%20two%20steps%3A%5Cn%5Cn1.%20Ensure%20Docker%20is%20running.%20For%20example%2C%20open%20Rancher%20Desktop.%5Cn2.%20Run%20%60.%2Fstart%60%20in%20your%20terminal%2C%20and%20open%20http%3A%2F%2Flocalhost%3A3000%20in%20your%20browser.%5Cn%5CnThe%20preview%20application%20does%20not%20include%20the%20top%20nav%20bar.%20Instead%2C%20navigate%20to%20the%20folder%20you%20want%20with%20the%20links%20in%20the%20home%20page.%20You%20can%20return%20to%20the%20home%20page%20at%20any%20time%20by%20clicking%20%5C%22IBM%20Quantum%20Documentation%20Preview%5C%22%20in%20the%20top-left%20of%20the%20header.%5Cn%5CnWarning%3A%20%60.%2Fstart%60%20does%20not%20check%20if%20there%20is%20a%20new%20version%20of%20the%20docs%20application%20available.%20You%20can%20run%20%60docker%20pull%20qiskit%2Fdocumentation%60%20to%20update%20to%20the%20latest%20version%20of%20the%20app.%20It%20will%20also%20ignore%20the%20API%20docs%20to%20speed%20things%20up%2C%20if%20you%20want%20to%20view%20them%2C%20run%20%60.%2Fstart%20--apis%60.%5Cn%5Cn%23%23%23%20API%20docs%20authors%3A%20How%20to%20preview%20your%20changes%5Cn%5CnAPI%20docs%20authors%20can%20preview%20their%20changes%20to%20one%20of%20the%20APIs%20by%20using%20the%20%60-a%60%20parameter%20to%20specify%20the%20path%20to%20the%20docs%20folder%3A%5Cn%5Cn1.%20Run%20%60npm%20run%20gen-api%20--%20-p%20%3Cpkg-name%3E%20-v%20%3Cversion%3E%20-a%20%3Cpath%2Fto%2Fdocs%2F_build%2Fhtml%3E%60.%5Cn2.%20Execute%20%60.%2Fstart%60%20and%20open%20up%20%60http%3A%2F%2Flocalhost%3A3000%60%2C%20as%20explained%20in%20the%20prior%20section.%5Cn%5Cn%23%23%20Jupyter%20notebooks%5Cn%5Cn%23%23%23%20Add%20a%20new%20notebook%5Cn%5CnWhen%20adding%20a%20new%20notebook%2C%20you'll%20need%20to%20tell%20the%20testing%20tools%20how%20to%20handle%20it.%5CnTo%20do%20this%2C%20add%20the%20file%20path%20to%20%60scripts%2Fconfig%2Fnotebook-testing.toml%60.%20There%20are%5Cnfour%20categories%3A%5Cn%5Cn-%20%60notebooks_normal_test%60%3A%20Notebooks%20to%20be%20run%20normally%20in%20CI.%20These%20notebooks%5Cn%20%20can't%20submit%20jobs%20as%20the%20queue%20times%20are%20too%20long%20and%20it%20will%20waste%5Cn%20%20resources.%20You%20_can_%20interact%20with%20IBM%20Quantum%20to%20retrieve%20jobs%20and%20backend%5Cn%20%20information.%5Cn-%20%60notebooks_that_submit_jobs%60%3A%20Notebooks%20that%20submit%20jobs%2C%20but%20that%20are%20small%5Cn%20%20enough%20to%20run%20on%20a%205-qubit%20simulator.%20We%20will%20test%20these%20notebooks%20in%20CI%20by%5Cn%20%20patching%20%60least_busy%60%20to%20return%20a%205-qubit%20fake%20backend.%5Cn-%20%60notebooks_no_mock%60%3A%20For%20notebooks%20that%20can't%20be%20tested%20using%20the%205-qubit%5Cn%20%20simulator%20patch.%20We%20skip%20testing%20these%20in%20CI%20and%20instead%20run%20them%20twice%20per%5Cn%20%20month.%20Any%20notebooks%20with%20cells%20that%20take%20more%20than%20five%20minutes%20to%20run%20are%5Cn%20%20also%20deemed%20too%20big%20for%20CI.%20Try%20to%20avoid%20adding%20notebooks%20to%20this%20category%20if%5Cn%20%20possible.%5Cn-%20%60notebooks_exclude%60%3A%20Notebooks%20to%20be%20ignored.%5Cn%5CnIf%20your%20notebook%20uses%20the%20latex%20circuit%20drawer%20(%60qc.draw(%5C%22latex%5C%22)%60)%2C%20you%20must%5Cnalso%20add%20it%20to%20the%20%5C%22Check%20for%20notebooks%20that%20require%20LaTeX%5C%22%20step%20in%5Cn%60.github%2Fworkflows%2Fnotebook-test.yml%60.%5Cn%5Cn%23%23%23%20Execute%20notebooks%5Cn%5CnBefore%20submitting%20a%20new%20notebook%20or%20code%20changes%20to%20a%20notebook%2C%20you%20must%20run%5Cnthe%20notebook%20using%20%60tox%20--%20--write%20%3Cpath-to-notebook%3E%60%20and%20commit%20the%20results.%5CnIf%20the%20notebook%20submits%20jobs%2C%20also%20use%20the%20argument%20%60--submit-jobs%60.%20This%20means%5Cnwe%20can%20be%20sure%20all%20notebooks%20work%20and%20that%20users%20will%20see%20the%20same%20results%20when%5Cnthey%20run%20using%20the%20environment%20we%20recommend.%5Cn%5CnTo%20execute%20notebooks%20in%20a%20fixed%20Python%20environment%2C%20first%20install%20%60tox%60%20using%5Cn%5Bpipx%5D(https%3A%2F%2Fpipx.pypa.io%2Fstable%2F)%3A%5Cn%5Cn%60%60%60sh%5Cnpipx%20install%20tox%5Cn%60%60%60%5Cn%5CnYou%20also%20need%20to%20install%20a%20few%20system%20dependencies%3A%20TeX%2C%20Poppler%2C%20and%20graphviz.%5CnOn%20macOS%2C%20you%20can%20run%20%60brew%20install%20mactex-no-gui%20poppler%20graphviz%60.%20On%20Ubuntu%2C%5Cnyou%20can%20run%20%60apt-get%20install%20texlive-pictures%20texlive-latex-extra%20poppler-utils%5Cngraphviz%60.%5Cn%5Cn-%20To%20execute%20all%20notebooks%2C%20run%20tox.%5Cn%20%20%60%60%60sh%5Cn%20%20tox%5Cn%20%20%60%60%60%5Cn-%20To%20only%20execute%20specific%20notebooks%2C%20pass%20them%20as%20arguments.%5Cn%20%20%60%60%60sh%5Cn%20%20tox%20--%20path%2Fto%2Fnotebook.ipynb%20path%2Fto%2Fanother-notbook.ipynb%5Cn%20%20%60%60%60%5Cn-%20To%20write%20the%20execution%20results%20to%20the%20file%2C%20pass%20the%20%60--write%60%20argument.%5Cn%20%20%60%60%60sh%5Cn%20%20tox%20--%20optional%2Fpaths%2Fto%2Fnotebooks.ipynb%20--write%5Cn%20%20%60%60%60%5Cn%5CnWhen%20you%20make%20a%20pull%20request%20changing%20a%20notebook%20that%20doesn't%20submit%20jobs%2C%20you%5Cncan%20get%20a%20version%20of%20that%20notebook%20that%20was%20executed%20by%20tox%20from%20CI.%20To%20do%5Cnthis%2C%20click%20%5C%22Show%20all%20checks%5C%22%20in%20the%20info%20box%20at%20the%20bottom%20of%20the%20pull%20request%5Cnpage%20on%20GitHub%2C%20then%20choose%20%5C%22Details%5C%22%20for%20the%20%5C%22Test%20notebooks%5C%22%20job.%20From%20the%5Cnjob%20page%2C%20click%20%5C%22Summary%5C%22%2C%20then%20download%20%5C%22Executed%20notebooks%5C%22.%20Otherwise%2C%20if%5Cnyour%20notebook%20does%20submit%20jobs%2C%20you%20need%20to%20run%20it%20locally%20using%20the%20steps%5Cnmentioned%20earlier.%5Cn%5Cn%23%23%23%20Ignore%20warnings%20in%20your%20notebook%5Cn%5CnWe%20don't%20want%20users%20to%20see%20warnings%20that%20can%20be%20avoided%2C%20so%20it's%20best%20to%20fix%5Cnthe%20code%20to%20avoid%20them.%20However%2C%20if%20a%20warning%20is%20unavoidable%2C%20you%20can%20stop%20it%5Cnblocking%20CI%20by%20adding%20an%20%60ignore-warnings%60%20tag%20to%20the%20cell.%20In%20VSCode%2C%5Cnright-click%20the%20cell%2C%20choose%20%5C%22Add%20cell%20tag%5C%22%2C%20type%20%60ignore-warnings%60%2C%20then%20press%5Cn%5C%22Enter%5C%22.%20In%20Jupyter%20notebook%20(depending%20on%20version)%2C%20choose%20View%20%3E%20Right%5CnSidebar%20%3E%20Show%20Notebook%20Tools%2C%20then%20under%20%5C%22Common%20Tools%5C%22%20add%20a%20tag%20with%20text%5Cn%60ignore-warnings%60.%5Cn%5Cn%23%23%23%20Add%20extra%20code%20checks%20to%20your%20notebook%5Cn%5CnOur%20CI%20checks%20notebooks%20run%20from%20start%20to%20finish%20without%20errors%20or%20warnings.%5CnYou%20can%20add%20extra%20checks%20in%20notebooks%20to%20catch%20other%20unexpected%20behavior.%5Cn%5CnFor%20example%2C%20say%20we%20claim%20a%20cell%20always%20returns%20the%20string%20%600011%60.%20It%20would%20be%5Cnembarassing%20if%20this%20was%20not%20true.%20We%20can%20assert%20this%20in%20CI%20by%20adding%20the%5Cnfollowing%20code%20cell%2C%20and%20hide%20it%20from%20users%20with%20a%20%60remove-cell%60%20tag.%5Cn%5Cn%60%60%60python%5Cn%23%20Confirm%20output%20is%20what%20we%20expect.%5Cnassert%20_%20%3D%3D%20'0011'%5Cn%60%60%60%5Cn%5CnIn%20Jupyter%20notebooks%2C%20the%20underscore%20%60_%60%20variable%20stores%20the%20value%20of%20the%5Cnprevious%20cell%20output.%20You%20should%20also%20add%20a%20comment%20like%5Cn%60%23%20Confirm%20output%20is%20what%20we%20expect%60%20so%20that%20authors%20know%20this%5Cnblock%20is%20only%20for%20testing.%20Make%20sure%20you%20add%20the%20tag%20%60remove-cell%60.%5CnIf%20something%20ever%20causes%20this%20value%20to%5Cnchange%2C%20CI%20will%20alert%20us.%5Cn%5Cn%23%23%23%20Lint%20notebooks%5Cn%5CnWe%20use%20%5B%60squeaky%60%5D(https%3A%2F%2Fgithub.com%2Ffrankharkins%2Fsqueaky)%20to%20lint%20our%5Cnnotebooks.%20First%20install%20%60tox%60%20using%20%5Bpipx%5D(https%3A%2F%2Fpipx.pypa.io%2Fstable%2F).%5Cn%5Cn%60%60%60sh%5Cnpipx%20install%20tox%5Cn%60%60%60%5Cn%5CnTo%20check%20if%20a%20notebook%20needs%20linting%3A%5Cn%5Cn%60%60%60sh%5Cn%23%20Check%20all%20notebooks%20in%20.%2Fdocs%5Cntox%20-e%20lint%20--%20docs%2F**%2F*.ipynb%5Cn%60%60%60%5Cn%5CnTo%20fix%20problems%20in%20a%20notebooks%2C%20run%3A%5Cn%5Cn%60%60%60sh%5Cntox%20-e%20fix%20--%20path%2Fto%2Fnotebook%5Cn%60%60%60%5Cn%5CnOr%2C%20you%20can%20retrieve%20an%20executed%20and%20linted%20version%20of%20your%20notebook%20from%20CI%5Cnfollowing%20the%20steps%20at%20the%20end%20of%20the%20%5BExecute%20notebooks%5D(%23execute-notebooks)%5Cnsection.%5Cn%5CnIf%20you%20use%20the%20Jupyter%20notebook%20editor%2C%20consider%20adding%20squeaky%20as%20a%20%5Bpre-save%5Cnhook%5D(https%3A%2F%2Fgithub.com%2Ffrankharkins%2Fsqueaky%3Ftab%3Dreadme-ov-file%23jupyter-pre-save-hook).%5CnThis%20will%20lint%20your%20notebooks%20as%20you%20save%20them%2C%20so%20you%20never%20need%20to%20worry%5Cnabout%20it.%5Cn%5Cn%23%23%20Check%20for%20broken%20links%5Cn%5CnWe%20have%20two%20broken%20link%20checkers%3A%20for%20internal%20links%20and%20for%20external%20links.%5Cn%5CnTo%20check%20internal%20links%3A%5Cn%5Cn%60%60%60bash%5Cn%23%20Only%20check%20non-API%20docs%5Cnnpm%20run%20check%3Ainternal-links%5Cn%5Cn%23%20You%20can%20add%20any%20of%20the%20below%20arguments%20to%20also%20check%20API%20docs.%5Cnnpm%20run%20check%3Ainternal-links%20--%20--current-apis%20--dev-apis%20--historical-apis%20--qiskit-legacy-release-notes%5Cn%5Cn%23%20Or%2C%20run%20all%20the%20checks.%20Although%20this%20only%20checks%20non-API%20docs.%5Cnnpm%20run%20check%5Cn%60%60%60%5Cn%5CnTo%20check%20external%20links%3A%5Cn%5Cn%60%60%60bash%5Cn%23%20Specify%20the%20files%20you%20want%20after%20%60--%60%5Cnnpm%20run%20check%3Aexternal-links%20--%20docs%2Fguides%2Findex.md%20docs%2Fguides%2Fcircuit-execution.mdx%5Cn%5Cn%23%20You%20can%20also%20use%20globs%5Cnnpm%20run%20check%3Aexternal-links%20--%20'docs%2Fguides%2F*'%20'!docs%2Fguides%2Findex.mdx'%5Cn%60%60%60%5Cn%5Cn%23%23%20Check%20for%20orphan%20pages%5Cn%5CnEvery%20file%20should%20have%20a%20home%20in%20one%20of%20the%20%60_toc.json%60%20files.%5Cn%5CnTo%20check%20for%20orphaned%20pages%2C%20run%3A%5Cn%5Cn%60%60%60bash%5Cn%23%20Only%20check%20non-API%20docs%5Cnnpm%20run%20check%3Aorphan-pages%5Cn%5Cn%23%20You%20can%20also%20check%20API%20docs%5Cnnpm%20run%20check%3Aorphan-pages%20--%20--apis%5Cn%5Cn%23%20Or%2C%20run%20all%20the%20checks.%20However%20this%20will%20skip%20the%20API%20docs%5Cnnpm%20run%20check%5Cn%60%60%60%5Cn%5Cn%23%23%20Check%20page%20metadata%5Cn%5CnEvery%20file%20needs%20to%20have%20a%20%60title%60%20and%20%60description%60%2C%20as%20explained%20in%20%5BPage%20Metadata%5D(%23page-metadata)%20The%20%60lint%60%20job%20in%20CI%20will%20fail%20with%20instructions%20for%20any%20bad%20file.%5Cn%5CnYou%20can%20also%20check%20for%20valid%20metadata%20locally%3A%5Cn%5Cn%60%60%60bash%5Cn%23%20Only%20check%20file%20metadata%5Cnnpm%20run%20check%3Ametadata%5Cn%5Cn%23%20By%20default%2C%20only%20the%20non-API%20docs%20are%20checked.%20You%20can%20add%20the%5Cn%23%20below%20argument%20to%20also%20check%20API%20docs.%5Cnnpm%20run%20check%3Ametadata%20--%20--apis%5Cn%5Cn%23%20Or%2C%20run%20all%20the%20checks.%20Although%20this%20only%20checks%20non-API%20docs.%5Cnnpm%20run%20check%5Cn%60%60%60%5Cn%5Cn%23%23%20Spellcheck%5Cn%5CnWe%20use%20%5BcSpell%5D(https%3A%2F%2Fcspell.org)%20to%20check%20for%20spelling.%20The%20%60lint%60%20job%20in%20CI%20will%20fail%20if%20there%20are%20spelling%20issues.%5Cn%5CnThere%20are%20two%20ways%20to%20check%20spelling%20locally%2C%20rather%20than%20needing%20CI.%5Cn%5Cn1.%5Cn%5Cn%60%60%60bash%5Cn%23%20Only%20check%20spelling%5Cnnpm%20run%20check%3Aspelling%5Cn%5Cn%23%20Or%2C%20run%20all%20the%20checks%5Cnnpm%20run%20check%5Cn%60%60%60%5Cn%5Cn2.%20Use%20the%20VSCode%20extension%20%5BCode%20Spell%20Checker%5D(https%3A%2F%2Fmarketplace.visualstudio.com%2Fitems%3FitemName%3Dstreetsidesoftware.code-spell-checker).%5Cn%5Cn%23%23%23%20Fixing%20false%20positives%5Cn%5CnThere%20are%20two%20ways%20to%20deal%20with%20cSpell%20incorrectly%20complaining%20about%20a%20word%2C%20such%20as%20abbreviations.%5Cn%5Cn1.%20Ignore%20the%20word%20in%20the%20local%20markdown%20file%20by%20adding%20a%20comment%20to%20the%20file%2C%20like%20below.%20The%20word%20is%20not%20case-sensitive%2C%20and%20the%20comment%20can%20be%20placed%20anywhere.%5Cn%5Cn%60%60%60%5Cn%7B%2F*%20cspell%3Aignore%20hellllooooo%2C%20ayyyyy%20*%2F%7D%5Cn%5Cn%23%20Hellllooooo!%5Cn%5CnAyyyyy%2C%20this%20is%20a%20fake%20description.%5Cn%60%60%60%5Cn%5Cn2.%20If%20the%20word%20is%20a%20name%2C%20add%20it%20to%20the%20%60scripts%2Fconfig%2Fcspell%2Fdictionaries%2Fpeople.txt%60%20file.%20If%20it%20is%20a%20scientific%20or%20quantum%20specific%20word%2C%20add%20it%20to%20the%20%60scripts%2Fconfig%2Fcspell%2Fdictionaries%2Fqiskit.txt%60%20file.%20If%20it%20doesn't%20fit%20in%20either%20category%2C%20add%20it%20to%20the%20%60words%60%20section%20in%20%60scripts%2Fconfig%2Fcspell%2FcSpell.json%60.%20The%20word%20is%20not%20case-sensitive.%5Cn%5CnIf%20the%20word%20appears%20in%20multiple%20files%2C%20prefer%20the%20second%20approach%20to%20add%20it%20to%20one%20of%20the%20dictionaries%20or%20%60cSpell.json%60.%5Cn%5Cn%23%23%20Check%20that%20pages%20render%5Cn%5CnIt's%20possible%20to%20write%20broken%20pages%20that%20crash%20when%20loaded.%20This%20is%20usually%20due%20to%20syntax%20errors.%5Cn%5CnTo%20check%20that%20all%20the%20non-API%20docs%20render%3A%5Cn%5Cn1.%20Start%20up%20the%20local%20preview%20with%20%60.%2Fstart%60%20by%20following%20the%20instructions%20at%20%5BPreview%20the%20docs%20locally%5D(%23preview-the-docs-locally)%5Cn2.%20In%20a%20new%20tab%2C%20%60npm%20run%20check%3Apages-render%20--%20--non-api%60%5Cn%5CnYou%20can%20also%20check%20that%20API%20docs%20render%20by%20using%20any%20of%20these%20arguments%3A%20%60npm%20run%20check%3Apages-render%20--%20--non-api%20--qiskit-release-notes%20--current-apis%20--dev-apis%20--historical-apis%60.%20Warning%20that%20this%20is%20exponentially%20slower.%5Cn%5CnCI%20will%20check%20on%20every%20PR%20that%20any%20changed%20files%20render%20correctly.%20We%20also%20run%20a%20weekly%20cron%20job%20to%20check%20that%20every%20page%20renders%20correctly.%5Cn%5Cn%23%23%20Format%20README%20and%20TypeScript%20files%5Cn%5CnRun%20%60npm%20run%20fmt%60%20to%20automatically%20format%20the%20README%2C%20%60.github%60%20folder%2C%20and%20%60scripts%2F%60%20folder.%20You%20should%20run%20this%20command%20if%20you%20get%20the%20error%20in%20CI%20%60run%20Prettier%20to%20fix%60.%5Cn%5CnTo%20check%20that%20formatting%20is%20valid%20without%20actually%20making%20changes%2C%20run%20%60npm%20run%20check%3Afmt%60%20or%20%60npm%20run%20check%60.%5Cn%5Cn%23%23%20Regenerate%20an%20existing%20API%20docs%20version%5Cn%5CnThis%20is%20useful%20when%20we%20make%20improvements%20to%20the%20API%20generation%20script.%5Cn%5CnYou%20can%20regenerate%20all%20API%20docs%20versions%20following%20these%20steps%3A%5Cn%5Cn1.%20Create%20a%20dedicated%20branch%20for%20the%20regeneration%20other%20than%20%60main%60%20using%20%60git%20checkout%20-b%20%3Cbranch-name%3E%60.%5Cn2.%20Ensure%20there%20are%20no%20pending%20changes%20by%20running%20%60git%20status%60%20and%20creating%20a%20new%20commit%20for%20them%20if%20necessary.%5Cn3.%20Run%20%60npm%20run%20regen-apis%60%20to%20regenerate%20all%20API%20docs%20versions%20for%20%60qiskit%60%2C%20%60qiskit-ibm-runtime%60%2C%20and%20%60qiskit-ibm-transpiler%60.%5Cn%5CnEach%20regenerated%20version%20will%20be%20saved%20as%20a%20distinct%20commit.%20If%20the%20changes%20are%20too%20large%20for%20one%20single%20PR%2C%20consider%20splitting%20it%20up%20into%20multiple%20PRs%20by%20using%20%60git%20cherry-pick%60%20or%20%60git%20rebase%20-i%60%20so%20each%20PR%20only%20has%20the%20commits%20it%20wants%20to%20target.%5Cn%5CnIf%20you%20only%20want%20to%20regenerate%20the%20latest%20stable%20minor%20release%20of%20each%20package%2C%20then%20add%20%60--current-apis-only%60%20as%20an%20argument%2C%20and%20in%20case%20you%20only%20want%20to%20regenerate%20versions%20of%20one%20package%2C%20then%20you%20can%20use%20the%20%60-p%20%3Cpkg-name%3E%60%20argument.%5Cn%5CnAlternatively%2C%20you%20can%20also%20regenerate%20one%20specific%20version%3A%5Cn%5Cn1.%20Choose%20which%20documentation%20you%20want%20to%20generate%20(%60qiskit%60%2C%20%60qiskit-ibm-runtime%60%2C%20or%20%60qiskit-ibm-transpiler%60)%20and%20its%20version.%5Cn2.%20Run%20%60npm%20run%20gen-api%20--%20-p%20%3Cpkg-name%3E%20-v%20%3Cversion%3E%60%2C%5Cn%20%20%20e.g.%20%60npm%20run%20gen-api%20--%20-p%20qiskit%20-v%200.45.0%60%5Cn%5CnIf%20the%20version%20is%20not%20for%20the%20latest%20stable%20minor%20release%20series%2C%20then%20add%20%60--historical%60%20to%20the%20arguments.%20For%20example%2C%20use%20%60--historical%60%20if%20the%20latest%20stable%20release%20is%200.45.%5C%5C*%20but%20you're%20generating%20docs%20for%20the%20patch%20release%200.44.3.%5Cn%5CnAdditionally%2C%20If%20you%20are%20regenerating%20a%20dev%20version%2C%20then%20you%20can%20add%20%60--dev%60%20as%20an%20argument%20and%20the%20documentation%20will%20be%20built%20at%20%60%2Fdocs%2Fapi%2F%3Cpkg-name%3E%2Fdev%60.%20For%20dev%20versions%2C%20end%20the%20%60--version%60%20in%20%60-dev%60%2C%20e.g.%20%60-v%201.0.0-dev%60.%20If%20a%20release%20candidate%20has%20already%20been%20released%2C%20use%20%60-v%201.0.0rc1%60%2C%20for%20example.%5Cn%5CnIn%20this%20case%2C%20no%20commit%20will%20be%20automatically%20created.%5Cn%5Cn%23%23%20Generate%20new%20API%20docs%5Cn%5CnThis%20is%20useful%20when%20new%20docs%20content%20is%20published%2C%20usually%20corresponding%20to%20new%20releases%20or%20hotfixes%20for%20content%20issues.%20If%20you're%20generating%20a%20patch%20release%2C%20also%20see%20the%20below%20subsection%20for%20additional%20steps.%5Cn%5Cn1.%20Choose%20which%20documentation%20you%20want%20to%20generate%20(%60qiskit%60%2C%20%60qiskit-ibm-runtime%60%2C%20or%20%60qiskit-ibm-transpiler%60)%20and%20its%20version.%5Cn2.%20Determine%20the%20full%20version%2C%20such%20as%20by%20looking%20at%20https%3A%2F%2Fgithub.com%2FQiskit%2Fqiskit%2Freleases%5Cn3.%20Download%20a%20CI%20artifact%20with%20the%20project's%20documentation.%20To%20find%20this%3A%5Cn%20%20%201.%20Pull%20up%20the%20CI%20runs%20for%20the%20stable%20commit%20that%20you%20want%20to%20build%20docs%20from.%20This%20should%20not%20be%20from%20a%20Pull%20Request%5Cn%20%20%202.%20Open%20up%20the%20%5C%22Details%5C%22%20for%20the%20relevant%20workflow.%5Cn%20%20%20%20%20%20-%20Qiskit%3A%20%5C%22Documentation%20%2F%20Build%20(push)%5C%22%5Cn%20%20%20%20%20%20-%20Runtime%3A%20%5C%22CI%20%2F%20Build%20documentation%20(push)%5C%22%5Cn%20%20%203.%20Click%20the%20%5C%22Summary%5C%22%20page%20at%20the%20top%20of%20the%20left%20navbar.%5Cn%20%20%204.%20Scroll%20down%20to%20%5C%22Artifacts%5C%22%20and%20look%20for%20the%20artifact%20related%20to%20documentation%2C%20such%20as%20%60html_docs%60.%5Cn%20%20%205.%20Download%20the%20artifact%20by%20clicking%20on%20its%20name.%5Cn4.%20Rename%20the%20downloaded%20zip%20file%20with%20its%20version%20number%2C%20e.g.%20%600.45.zip%60%20for%20an%20artifact%20from%20%60qiskit%20v0.45.2%60.%5Cn5.%20Upload%20the%20renamed%20zip%20file%20to%20https%3A%2F%2Fibm.ent.box.com%2Ffolder%2F246867452622%5Cn6.%20Share%20the%20file%20by%20clicking%20the%20%60Copy%20shared%20link%60%20button%5Cn7.%20Select%20%60People%20with%20the%20link%60%20and%20go%20to%20%60Link%20Settings%60.%5Cn8.%20Under%20%60Link%20Expiration%60%20select%20%60Disable%20Shared%20Link%20on%60%20and%20set%20an%20expiration%20date%20of%20~10%20years%20into%20the%20future.%5Cn9.%20Copy%20the%20direct%20link%20at%20the%20end%20of%20the%20%60Shared%20Link%20Settings%60%20tab.%5Cn10.%20Modify%20the%20%60scripts%2Fconfig%2Fapi-html-artifacts.json%60%20file%2C%20adding%20the%20new%20versions%20with%20the%20direct%20link%20from%20step%209.%5Cn11.%20Run%20%60npm%20run%20gen-api%20--%20-p%20%3Cpkg-name%3E%20-v%20%3Cversion%3E%60%2C%5Cn%20%20%20%20e.g.%20%60npm%20run%20gen-api%20--%20-p%20qiskit%20-v%200.45.0%60%5Cn%5CnIf%20you%20are%20regenerating%20a%20dev%20version%2C%20then%20you%20can%20add%20%60--dev%60%20as%20an%20argument%20and%20the%20documentation%20will%20be%20built%20at%20%60%2Fdocs%2Fapi%2F%3Cpkg-name%3E%2Fdev%60.%20For%20dev%20versions%2C%20end%20the%20%60--version%60%20in%20%60-dev%60%2C%20e.g.%20%60-v%201.0.0-dev%60.%20If%20a%20release%20candidate%20has%20already%20been%20released%2C%20use%20%60-v%201.0.0rc1%60%2C%20for%20example.%5Cn%5CnIn%20case%20you%20want%20to%20save%20the%20current%20version%20and%20convert%20it%20into%20a%20historical%20one%2C%20you%20can%20run%20%60npm%20run%20make-historical%20--%20-p%20%3Cpkg-name%3E%60%20beforehand.%5Cn%5Cn%23%23%23%20Generate%20patch%20releases%5Cn%5CnFor%20example%2C%20if%20the%20current%20docs%20are%20for%200.45.2%20but%20you%20want%20to%20generate%200.45.3.%5Cn%5CnFollow%20the%20same%20process%20above%20for%20new%20API%20docs%2C%20other%20than%3A%5Cn%5Cn-%20When%20uploading%20the%20artifact%2C%20overwrite%20the%20existing%20file%20with%20the%20new%20one.%20Be%20careful%20to%20follow%20the%20above%20steps%20to%20change%20%5C%22Link%20Expiration%5C%22!%5Cn%5CnIf%20the%20version%20is%20not%20for%20the%20latest%20stable%20minor%20release%20series%2C%20then%20add%20%60--historical%60%20to%20the%20arguments.%20For%20example%2C%20use%20%60--historical%60%20if%20the%20latest%20stable%20release%20is%200.45.%5C%5C*%20but%20you're%20generating%20docs%20for%20the%20patch%20release%200.44.3.%5Cn%5Cn%23%23%23%20View%20diff%20for%20%60objects.inv%60%5Cn%5CnSince%20%60objects.inv%60%20is%20compressed%2C%20we%20can't%20review%20changes%20through%20%60git%20diff%60.%20Git%20_does_%20tell%20you%20if%20the%20file%20has%20changed%2C%20but%20this%20isn't%20that%20helpful%20as%20the%20compressed%20file%20can%20be%20different%20even%20if%20the%20uncompressed%20contents%20are%20the%20same.%5CnIf%20you%20want%20to%20see%20the%20diff%20for%20the%20uncompressed%20contents%2C%20first%20install%20%5B%60sphobjinv%60%5D(https%3A%2F%2Fgithub.com%2Fbskinn%2Fsphobjinv).%5Cn%5Cn%60%60%60sh%5Cnpipx%20install%20sphobjinv%5Cn%60%60%60%5Cn%5CnThe%20add%20the%20following%20to%20your%20%60.gitconfig%60%20(usually%20found%20at%20%60~%2F.gitconfig%60).%5Cn%5Cn%60%60%60%5Cn%5Bdiff%20%5C%22objects_inv%5C%22%5D%5Cn%20%20textconv%20%3D%20sh%20-c%20'sphobjinv%20convert%20plain%20%5C%22%240%5C%22%20-'%5Cn%60%60%60%5Cn%5Cn%23%23%23%20Dependabot%20-%20upgrade%20notebook%20testing%20version%5Cn%5CnWhen%20a%20new%20version%20of%20an%20API%20is%20released%2C%20we%20should%20also%20update%20%60nb-tester%2Frequirements.txt%60%20to%20ensure%20that%20our%20notebooks%20still%20work%20with%20the%20latest%20version%20of%20the%20API.%20You%20can%20do%20this%20upgrade%20either%20manually%20or%20wait%20for%20Dependabot's%20automated%20PR.%5Cn%5CnDependabot%20will%20fail%20to%20run%20at%20first%20due%20to%20not%20having%20access%20to%20the%20token.%20To%20fix%20this%2C%20have%20someone%20with%20write%20access%20trigger%20CI%20for%20the%20PR%2C%20such%20as%20by%20merging%20main%20or%20closing%20then%20reopening%20the%20issue.%5Cn%5CnYou%20can%20land%20the%20API%20generation%20separately%20from%20the%20%60requirements.txt%60%20version%20upgrade.%20It's%20high%20priority%20to%20get%20out%20new%20versions%20of%20the%20API%20docs%20ASAP%2C%20so%20you%20should%20not%20block%20that%20on%20the%20notebook%20version%20upgrade%20if%20you%20run%20into%20any%20complications%20like%20failing%20notebooks.%5Cn%5Cn%23%23%20Deploy%20guides%20%26%20API%20docs%5Cn%5CnSee%20the%20section%20%5C%22Syncing%20content%20with%20open%20source%20repo%5C%22%20in%20the%20internal%20docs%20repo's%20README.%5Cn%5Cn%23%20How%20to%20write%20the%20documentation%5Cn%5CnRefer%20to%20our%20%5Bstyle%20guide%5D(%2F%2Fscnc%2Fqiskit-documentation%2Ftree%2Fmain%2Fstyle-guide.md)%20for%20technical%20writing%20guidance.%5Cn%5CnWe%20use%20%5BMDX%5D(https%3A%2F%2Fmdxjs.com)%2C%20which%20is%20like%20normal%20markdown%20but%20adds%20extensions%20for%20custom%20components%20we%20have.%5Cn%5CnRefer%20to%20the%20%5BCommon%20Markdown%20syntax%5D(https%3A%2F%2Fcommonmark.org%2F)%20for%20a%20primer%20on%20Markdown.%20The%20below%20guide%20focuses%20on%20the%20other%20features%20you%20can%20use%20when%20writing%20docs.%5Cn%5Cn%23%23%20How%20to%20add%20a%20new%20page%5Cn%5CnChoose%20which%20existing%20folder%20from%20%60docs%2F%60%20your%20new%20page%20belongs%20to%20(probably%20%60guides%60).%5Cn%5CnNext%2C%20choose%20the%20file%20name.%20The%20file%20name%20will%20determine%20the%20URL.%20For%20example%2C%20%60start%2Fmy-new-page.mdx%60%20results%20in%20the%20URL%20%60start%2Fmy-new-page%60.%20Choose%20a%20file%20name%20that%20will%20be%20stable%20over%20the%20page's%20lifespan%20and%20that%20is%20unlikely%20to%20clash%20with%20other%20topics.%20Use%20%60-%60%20rather%20than%20%60_%60%20as%20the%20delimiter.%20You%20can%20also%20ask%20for%20help%20choosing%20a%20name%20in%20the%20GitHub%20issue%20or%20pull%20request.%5Cn%5CnIf%20your%20file%20will%20have%20non-trivial%20code%20in%20it%2C%20please%20create%20a%20Jupyter%20notebook%20ending%20in%20%60.ipynb%60%2C%20rather%20than%20an%20MDX%20file.%20We%20prefer%20Jupyter%20notebooks%20when%20there%20is%20code%20because%20we%20have%20tests%20to%20make%20sure%20that%20the%20code%20still%20executes%20properly%2C%20whereas%20MDX%20is%20not%20tested.%5Cn%5CnAdd%20the%20file%20to%20these%20places%3A%5Cn%5Cn-%20The%20folder's%20%60_toc.json%60%2C%20such%20as%20%60guides%2F_toc.json%60.%20The%20%60title%60%20will%20show%20up%20in%20the%20left%20side%20bar.%20Note%20that%20the%20%60url%60%20leaves%20off%20the%20file%20extension.%5Cn-%20The%20appropriate%20%5C%22index%5C%22%20page%20in%20the%20Development%20workflow%20section%2C%20such%20as%20%60guides%2Fmap-problem-to-circuits%60%20AND%20the%20Tools%20section%20in%20the%20%60_toc.json%60%20file.%20Or%2C%20in%20the%20rare%20case%20that%20it%20doesn't%20belong%20on%20any%20of%20these%20pages%2C%20list%20it%20in%20%60scripts%2Fjs%2Fcommands%2FcheckPatternsIndex.ts%60%20in%20the%20ALLOWLIST_MISSING_FROM_INDEX%20or%20the%20ALLOWLIST_MISSING_FROM_TOC%20section.%20For%20example%2C%20%60%5C%22%2Fguides%2Fqiskit-code-assistant%5C%22%60.%5Cn-%20qiskit_bot.yaml.%20Everyone%20listed%20under%20the%20file%20name%20is%20notified%20any%20time%20the%20file%20is%20updated.%20If%20someone%20wants%20to%20be%20listed%20as%20an%20owner%20but%20does%20not%20want%20to%20receive%20notifications%2C%20put%20their%20ID%20in%20single%20quotes.%20For%20example%2C%20-%20%5C%22%60%40NoNotifications%60%5C%22%5Cn%5Cn%23%23%20Page%20metadata%5Cn%5CnEvery%20page%20must%20set%20a%20%60title%60%20and%20%60description%60%3A%5Cn%5Cn-%20The%20title%20is%20used%20for%20browser%20tabs%20and%20the%20top%20line%20of%20search%20results.%20It%20should%20usually%20match%20the%20title%20used%20in%20the%20%60_toc.json%60%20file.%5Cn-%20The%20description%20should%20describe%20the%20page%20in%20at%20least%2050%20but%20no%20more%20than%20160%20characters%2C%20ideally%20using%20some%20keywords.%20The%20description%20is%20what%20shows%20up%20as%20the%20text%20in%20search%20results.%20See%20https%3A%2F%2Fgithub.com%2FQiskit%2Fdocumentation%2Fissues%2F131%20for%20some%20tips.%5Cn%5CnIn%20MDX%20files%2C%20set%20the%20metadata%20at%20the%20top%20of%20the%20file%20like%20this%3A%5Cn%5Cn%60%60%60%5Cn---%5Cntitle%3A%20Representing%20quantum%20computers%5Cndescription%3A%20Learn%20about%20coupling%20maps%2C%20basis%20gates%2C%20and%20backend%20errors%20for%20transpiling%5Cn---%5Cn%60%60%60%5Cn%5CnIn%20Jupyter%20notebooks%2C%20set%20%60title%60%20and%20%60description%60%20in%20the%20%60metadata%60%20section%20for%20the%20file.%20In%20VSCode%2C%20you%20can%20set%20up%20the%20metadata%20with%20these%20instructions%3A%5Cn%5Cn1.%20Open%20up%20the%20file%20with%20the%20%5C%22Open%20With...%5C%22%20option%20(one%20way%20to%20do%20this%20is%20to%20right-click%20the%20file%20name%20to%20find%20the%20%5C%22Open%20With...%5C%22%20option)%20and%20then%20%5C%22Text%20Editor%5C%22.%5Cn2.%20Scroll%20down%20to%20the%20bottom%20of%20the%20file%20for%20the%20top-level%20key%20%5C%22metadata%5C%22.%20Ensure%20that%20this%20is%20the%20metadata%20for%20the%20entire%20file%20and%20not%20for%20a%20single%20code%20block.%20You%20should%20see%20in%20the%20%5C%22metadata%5C%22%20section%20other%20entries%20like%20%5C%22language_info%5C%22%20and%20%5C%22nbconvert_exporter%5C%22.%5Cn3.%20Add%20new%20keys%20in%20the%20%5C%22metadata%5C%22%20section%20for%20%5C%22title%5C%22%20and%20%5C%22description%5C%22.%5Cn%5Cn%60%60%60json%5Cn%5C%22metadata%5C%22%3A%20%7B%5Cn%20%20%5C%22description%5C%22%3A%20%5C%22Get%20started%20using%20Qiskit%20with%20IBM%20Quantum%20hardware%20in%20this%20Hello%20World%20example%5C%22%2C%5Cn%20%20%5C%22title%5C%22%3A%20%5C%22Hello%20world%5C%22%2C%5Cn%20%20%5C%22celltoolbar%5C%22%3A%20%5C%22Raw%20Cell%20Format%5C%22%2C%5Cn%20%20%5C%22kernelspec%5C%22%3A%20%7B%20...%5Cn%7D%5Cn%60%60%60%5Cn%5Cn%23%23%20Links%5Cn%5CnInternal%20URLs%20referring%20to%20other%20docs%20pages%20should%20start%20with%20%60%2F%60%20and%20not%20include%20the%20file%20extension.%20For%20example%3A%5Cn%5Cn-%20%60%5BQiskit%20SDK%5D(%2Fapi%2Fqiskit)%60%5Cn-%20%60%5BBit%20ordering%20in%20the%20Qiskit%20SDK%5D(%2Fguides%2Fbit-ordering)%60%5Cn%5CnExternal%20URLs%20should%20use%20the%20entire%20URL%2C%20such%20as%20%60%5BGitHub%5D(https%3A%2F%2Fgithub.com)%60.%5Cn%5Cn%23%23%20Images%5Cn%5CnImages%20are%20stored%20in%20the%20%60public%2Fimages%60%20folder.%20You%20should%20use%20subfolders%20to%20organize%20the%20files.%20For%20example%2C%20images%20for%20%60guides%2Fmy-file.mdx%60%20should%20be%20stored%20like%20%60public%2Fimages%2Fguides%2Fmy-file%2Fimg1.png%60.%5Cn%5CnTo%20use%20the%20image%3A%5Cn%5Cn%60%60%60markdown%5Cn!%5BAlt%20text%20for%20the%20image%5D(%2Fimages%2Fguides%2Fyour-file%2Fyour_image.png)%5Cn%60%60%60%5Cn%5CnTo%20add%20an%20inline%20images%3A%5Cn%5Cn%60%60%60markdown%5CnInline%20!%5BAlt%20text%20for%20the%20image%5D(%2Fimages%2Fguides%2Fyour-file%2Fyour_image.png)%20image%5Cn%60%60%60%5Cn%5CnTo%20include%20a%20caption%3A%5Cn%5Cn%60%60%60markdown%5Cn!%5BAlt%20text%20for%20the%20image%5D(%2Fimages%2Fguides%2Fyour-file%2Fyour_image.png%20%5C%22Image%20caption%5C%22)%5Cn%60%60%60%5Cn%5CnYou%20can%20include%20a%20version%20of%20the%20image%20to%20be%20with%20the%20dark%20theme.%20You%20only%20need%20to%20create%20an%20image%20with%20the%20same%20name%20ending%20in%20%60%40dark%60.%20So%20for%20example%2C%20if%20you%20have%20a%20%60sampler.png%60%20image%2C%20the%20dark%20version%20would%20be%20%60sampler%40dark.png%60.%20This%20is%20important%20for%20images%20that%20have%20a%20white%20background.%5Cn%5Cn%23%23%20Videos%5Cn%5CnVideos%20are%20stored%20in%20the%20%60public%2Fvideos%60%20folder.%20You%20should%20use%20subfolders%20to%20organize%20the%20files.%20For%20example%2C%20images%20for%20%60guides%2Fmy-file.mdx%60%20should%20be%20stored%20like%20%60public%2Fvideos%2Fguides%2Fmy-file%2Fvideo1.mp4%60.%5Cn%5CnTo%20add%20a%20video%3A%5Cn%5Cn%60%60%60markdown%5Cn%3Cvideo%20title%3D%5C%22Write%20a%20description%20of%20the%20video%20here%20as%20'alt%20text'%20for%20accessibility.%5C%22%20className%3D%5C%22max-w-auto%20h-auto%5C%22%20controls%3E%5Cn%20%20%20%20%3Csource%20src%3D%5C%22%2Fvideos%2Fguides%2Fsessions%2Fdemo.mp4%5C%22%20type%3D%5C%22video%2Fmp4%5C%22%3E%3C%2Fsource%3E%5Cn%3C%2Fvideo%3E%5Cn%60%60%60%5Cn%5Cn%23%23%20Math%5Cn%5CnWe%20use%20%5BLaTeX%5D(https%3A%2F%2Fwww.latex-project.org)%20to%20write%20math%2C%20which%20gets%20rendered%20by%20the%20library%20%5BKaTeX%5D(https%3A%2F%2Fkatex.org).%5Cn%5CnInline%20math%20expressions%20should%20start%20with%20%60%24%60%20and%20end%20with%20%60%24%60%2C%20e.g.%20%60%24%5C%5Cfrac%7B123%7D%7B2%7D%24%60.%5Cn%5CnMulti-line%20expressions%20should%20start%20with%20%60%24%24%60%20and%20end%20with%20%60%24%24%60%3A%5Cn%5Cn%60%60%60markdown%5Cn%24%24%5CnL%20%3D%20%5C%5Cfrac%7B123%7D%7B2%7D%20%5C%5Crho%20v%5E2%20S%20C_1s%5Cn%24%24%5Cn%60%60%60%5Cn%5Cn%23%23%20Tables%5Cn%5CnTables%20are%20supported%3A%20https%3A%2F%2Fwww.markdownguide.org%2Fextended-syntax%2F.%5Cn%5Cn%23%23%20Comments%5Cn%5CnExample%20comment%3A%20%60%7B%2F*%20Comes%20from%20https%3A%2F%2Fqiskit.org%2Fdocumentation%2Fpartners%2Fqiskit_ibm_runtime%2Fgetting_started.html%20*%2F%7D%60%5Cn%5Cn%23%23%20Collapsible%20sections%5Cn%5CnFor%20content%20that%20you%20don't%20want%20to%20show%20by%20default%2C%20use%20a%20collapsible%20section.%20The%20user%20will%20need%20to%20expand%20the%20section%20to%20read%20its%20contents.%20Refer%20to%20GitHub's%20guide%20on%20%5B%60%3Cdetails%3E%60%20and%20%60%3Csummary%3E%60%5D(https%3A%2F%2Fdocs.github.com%2Fen%2Fget-started%2Fwriting-on-github%2Fworking-with-advanced-formatting%2Forganizing-information-with-collapsed-sections).%5Cn%5Cn%23%23%20Footnotes%5Cn%5Cn%60%60%60%5CnFootnote%201%20link%5B%5Efirst%5D.%5Cn%5CnFootnote%202%20link%5B%5Esecond%5D.%5Cn%5CnDuplicated%20footnote%20reference%5B%5Esecond%5D.%5Cn%5Cn%5B%5Efirst%5D%3A%20Footnote%20**can%20have%20markup**%5Cn%5Cn%20%20%20%20and%20multiple%20paragraphs.%5Cn%5Cn%5B%5Esecond%5D%3A%20Second%20footnote%20text.%5Cn%60%60%60%5Cn%5Cn%23%23%20Custom%20components%5Cn%5CnThese%20are%20components%20that%20we%20expose%20through%20MDX.%20You%20can%20use%20them%20in%20both%5Cn%60.mdx%60%20and%20%60.ipynb%60%20files.%20In%20Jupyter%20notebooks%2C%20use%20Markdown%20cells.%5Cn%5Cn%23%23%23%20Admonitions%5Cn%5CnTo%20use%20an%20%60Admonition%60%2C%20use%20the%20following%20syntax%5Cn%5Cn%60%60%60mdx%5Cn%3CAdmonition%20type%3D%5C%22note%5C%22%3EThis%20is%20an%20example%20of%20a%20note.%3C%2FAdmonition%3E%5Cn%60%60%60%5Cn%5CnAvailable%20types%20are%20%60note%2C%20tip%2C%20info%2C%20caution%2C%20danger%60.%20This%20is%20what%20they%20look%20like%3A%5Cn%5Cn!%5Btypes%5D(https%3A%2F%2Fgithub.com%2FQiskit%2Fdocumentation%2Fassets%2F66339736%2F9911d171-2dbb-45a2-af84-6502d5fc0ae0)%5Cn%5CnBy%20default%2C%20the%20title%20is%20the%20%60type%60%20capitalized.%20You%20can%20customize%20it%20by%20setting%20%60title%60%3A%5Cn%5Cn%60%60%60mdx%5Cn%3CAdmonition%20type%3D%5C%22note%5C%22%20title%3D%5C%22Custom%20title%5C%22%3E%5Cn%20%20This%20is%20a%20__note__%20example%5Cn%3C%2FAdmonition%3E%5Cn%60%60%60%5Cn%5Cn%23%23%23%20Definition%20Tooltip%5Cn%5CnTo%20use%20a%20%60DefinitionTooltip%60%2C%20use%20the%20following%20syntax%3A%5Cn%5Cn%60%60%60mdx%5Cn%3CDefinitionTooltip%20definition%3D%5C%22Definition%20for%20the%20Term%5C%22%3ETerm%3C%2FDefinitionTooltip%3E%5Cn%60%60%60%5Cn%5CnFor%20full%20list%20of%20props%2C%20please%20check%20%5Bhere%5D(https%3A%2F%2Freact.carbondesignsystem.com%2F%3Fpath%3D%2Fdocs%2Fcomponents-definitiontooltip--playground%23component-api).%5Cn%5Cn%23%23%23%20Tabs%5Cn%5CnTo%20use%20a%20%60Tabs%60%20component%2C%20use%20the%20following%20syntax%3A%5Cn%5Cn%60%60%60mdx%5Cn%3CTabs%3E%5Cn%20%20%3CTabItem%20value%3D%5C%22pulses%5C%22%20label%3D%5C%22Pulses%5C%22%3E%5Cn%20%20%20%20This%20is%20the%20text%20for%20pulses%5Cn%20%20%3C%2FTabItem%3E%5Cn%5Cn%20%20%3CTabItem%20value%3D%5C%22qasm%5C%22%20label%3D%5C%22QASM%5C%22%3E%5Cn%20%20%20%20This%20is%20the%20text%20for%20QASM%5Cn%20%20%3C%2FTabItem%3E%5Cn%3C%2FTabs%3E%5Cn%60%60%60%5Cn%5CnBy%20default%2C%20the%20first%20tab%20is%20selected.%20You%20can%20change%20that%20by%20using%20the%20%60defaultValue%60%20prop.%5Cn%5Cn%60%60%60mdx%5Cn%3CTabs%20defaultValue%3D%5C%22qasm%5C%22%3E%5Cn%20%20%3CTabItem%20value%3D%5C%22pulses%5C%22%20label%3D%5C%22Pulses%5C%22%3E%5Cn%20%20%20%20This%20is%20the%20text%20for%20pulses%5Cn%20%20%3C%2FTabItem%3E%5Cn%5Cn%20%20%3CTabItem%20value%3D%5C%22qasm%5C%22%20label%3D%5C%22QASM%5C%22%3E%5Cn%20%20%20%20This%20is%20the%20text%20for%20QASM%5Cn%20%20%3C%2FTabItem%3E%5Cn%3C%2FTabs%3E%5Cn%60%60%60%5Cn%5CnThere%20are%20situations%20where%20you%20want%20to%20repeat%20the%20same%20tabs%20in%20several%20part%20of%20the%20page.%20In%20this%20situation%2C%20you%20can%20use%20the%20prop%20%60group%60%20to%20synchronize%20the%20selected%20tab%20in%20all%20usages.%5Cn%5Cn%60%60%60mdx%5Cn%3CTabs%20group%3D%5C%22my-group%5C%22%3E%5Cn%20%20%3CTabItem%20value%3D%5C%22pulses%5C%22%20label%3D%5C%22Pulses%5C%22%3E%5Cn%20%20%20%20This%20is%20the%20text%20for%20pulses%5Cn%20%20%3C%2FTabItem%3E%5Cn%5Cn%20%20%3CTabItem%20value%3D%5C%22qasm%5C%22%20label%3D%5C%22QASM%5C%22%3E%5Cn%20%20%20%20This%20is%20the%20text%20for%20QASM%5Cn%20%20%3C%2FTabItem%3E%5Cn%3C%2FTabs%3E%5Cn%60%60%60%5Cn%5CnThere%20is%20a%20specific%20use%20case%20where%20you%20want%20to%20show%20instructions%20for%20different%20operating%20systems.%20In%20this%20situation%2C%20you%20can%20replace%20the%20%60Tabs%60%20component%20by%20a%20%60OperatingSystemTabs%60.%20The%20default%20value%20of%20the%20tab%20will%20be%20selected%20based%20on%20the%20user's%20operating%20system.%5Cn%5Cn%60%60%60mdx%5Cn%3COperatingSystemTabs%3E%5Cn%20%20%3CTabItem%20value%3D%5C%22mac%5C%22%20label%3D%5C%22macOS%5C%22%3E%5Cn%20%20%20%20Open%20a%20terminal%20and%20write%20the%20command%5Cn%20%20%3C%2FTabItem%3E%5Cn%20%20%3CTabItem%20value%3D%5C%22linux%5C%22%20label%3D%5C%22Linux%5C%22%3E%5Cn%20%20%20%20Open%20a%20terminal%20and%20write%20the%20command%5Cn%20%20%3C%2FTabItem%3E%5Cn%20%20%3CTabItem%20value%3D%5C%22win%5C%22%20label%3D%5C%22Windows%5C%22%3E%5Cn%20%20%20%20Go%20to%20windows%2Frun%20and%20write%20%60cmd%60.%20It%20will%20open%20a%20command%20line.%20Execute%20this%5Cn%20%20%20%20command%5Cn%20%20%3C%2FTabItem%3E%5Cn%3C%2FOperatingSystemTabs%3E%5Cn%60%60%60%5Cn%5Cn%23%23%20Proper%20marking%20and%20attribution%5Cn%5Cn**All%20information%20needs%20to%20identify%2C%20mark%2C%20and%20attribute%20IBM%20and%20applicable%20third-party%20trademarks.**%20We%20do%20this%20the%20first%20time%20an%20IBM%20trademark%20appears%20on%20each%20page.%20See%20the%20%5BCopyright%20and%20trademark%20information%5D(https%3A%2F%2Fwww.ibm.com%2Flegal%2Fcopyright-trademark)%20page%20for%20more%20details.%5Cn%5CnSome%20companies%20require%20a%20special%20attribution%20notice.%20View%20a%20list%20of%20the%20companies%20to%20include%20in%20a%20special%20attribution%20notice%20at%20the%20%5BSpecial%20attributions%5D(https%3A%2F%2Fwww.ibm.com%2Flegal%2Fcopyright-trademark%23special)%20section%20of%20the%20IBM%20Legal%20site.%5Cn%5Cn%3Cdetails%3E%5Cn%3Csummary%3EA%20(non-exhaustive)%20list%20of%20trademarked%20names%20found%20in%20our%20docs%3A%3C%2Fsummary%3E%5Cn%5Cn-%20IBM%26reg%3B%5Cn-%20IBM%20Cloud%26reg%3B%5Cn-%20IBM%20Quantum%26trade%3B%5Cn%3C%2Fdetails%3E%5Cn%5Cn**Note**%3A%20Although%20Qiskit%20is%20a%20registered%20trademark%20of%20IBM%2C%20we%20do%20not%20mark%20it%20as%20such.%5Cn%5CnSee%20the%20Usage%20section%20of%20the%20IBM%20Quantum%20Experience%20Guide%20for%20guidance%20on%20when%20to%20use%20IBM%20and%20when%20to%20use%20IBM%20Quantum.%5Cn%5Cn%23%23%23%20Trademark%20symbols%5Cn%5CnTo%20create%20the%20symbols%20in%20markdown%3A%5Cn%5CnUse%20%60%26reg%3B%60%20to%20get%20%26reg%3B%20for%20registered%20trademarks.%5Cn%5Cnuse%20%60%26trade%3B%60%20to%20get%20%26trade%3B%20for%20nonregistered%20trademarks.%5Cn%5Cn%E2%9A%A0%EF%B8%8F%20**Note**%3A%20Do%20not%20include%20trademarks%20in%20headings.%20The%20code%20will%20display%20rather%20than%20the%20symbol.%5Cn%22%7D"},"zoneReducer":{"zoneDetail":"","newsDetail":""}}
Qiskit documentation
The documentation content home for https://docs.quantum.ibm.com (excluding API reference).
Improving IBM Quantum & Qiskit Documentation
Maintaining up-to-date documentation is a huge challenge for any software project, especially in a field like quantum computing where the pace at which advances in new research and technological capabilities happen incredibly fast. As a result, we greatly appreciate any who take the time to support us in keeping this content accurate and up to the highest quality standard possible to benefit the broadest range of users.
Read on for more information about how to support this project:
Best ways to contribute to Documentation
1. Report bugs, inaccuracies or general content issues
This is the quickest, easiest, and most helpful way to contribute to this project and improve the quality of Qiskit® and IBM Quantum™ documentation. There are a few different ways to report issues, depending on where it was found:
2. Suggest new content
If you think there are gaps in our documentation, or sections that could be expanded upon, we invite you to open a new content request issue here.
Not every new content suggestion is a good fit for docs, nor are we able to prioritize every request immediately. However, we will do our best to respond to content requests in a timely manner, and we greatly appreciate our community’s efforts in generating new ideas.
If you are interested in writing the new content yourself, or already have some draft work you think could be integrated, please also mention that in the issue description. If your content suggestion is accepted, we will let you know and work with you to get the content written and reviewed.
Please note: we DO NOT accept unsolicited PRs for new pages or large updates to existing content. The content that we include in docs is carefully planned and curated by our content team and must go through the appropriate review process to ensure the quality is of the highest possible standard before deploying to production. As a result we are very selective with which content suggestions are approved, and it is unlikely that PRs submitted without an associated approved content request will be accepted.
3. Validate existing issues
You can help the team prioritize already-open issues by doing the following:
4. Fix an open issue
You can look through the open issues we have in this repo and address them with a PR. We recommend focusing on issues with the “good first issue” label.
Before getting started on an issue, remember to do the following:
Once you have an issue to work on, see the “How to work with this repo” section below to get going, then open a PR.
Before opening a PR, remember to do the following:
npm run check
How to work with this repo
Prerequisites to building the docs locally
These tools will also run in CI, but it can be convenient when iterating to run the tools locally.
First, install the below software:
Then, install the dependencies with:
Preview the docs locally
You can preview the docs locally by following these two steps:
./start
in your terminal, and open http://localhost:3000 in your browser.The preview application does not include the top nav bar. Instead, navigate to the folder you want with the links in the home page. You can return to the home page at any time by clicking “IBM Quantum Documentation Preview” in the top-left of the header.
Warning:
./start
does not check if there is a new version of the docs application available. You can rundocker pull qiskit/documentation
to update to the latest version of the app. It will also ignore the API docs to speed things up, if you want to view them, run./start --apis
.API docs authors: How to preview your changes
API docs authors can preview their changes to one of the APIs by using the
-a
parameter to specify the path to the docs folder:npm run gen-api -- -p <pkg-name> -v <version> -a <path/to/docs/_build/html>
../start
and open uphttp://localhost:3000
, as explained in the prior section.Jupyter notebooks
Add a new notebook
When adding a new notebook, you’ll need to tell the testing tools how to handle it. To do this, add the file path to
scripts/config/notebook-testing.toml
. There are four categories:notebooks_normal_test
: Notebooks to be run normally in CI. These notebooks can’t submit jobs as the queue times are too long and it will waste resources. You can interact with IBM Quantum to retrieve jobs and backend information.notebooks_that_submit_jobs
: Notebooks that submit jobs, but that are small enough to run on a 5-qubit simulator. We will test these notebooks in CI by patchingleast_busy
to return a 5-qubit fake backend.notebooks_no_mock
: For notebooks that can’t be tested using the 5-qubit simulator patch. We skip testing these in CI and instead run them twice per month. Any notebooks with cells that take more than five minutes to run are also deemed too big for CI. Try to avoid adding notebooks to this category if possible.notebooks_exclude
: Notebooks to be ignored.If your notebook uses the latex circuit drawer (
qc.draw("latex")
), you must also add it to the “Check for notebooks that require LaTeX” step in.github/workflows/notebook-test.yml
.Execute notebooks
Before submitting a new notebook or code changes to a notebook, you must run the notebook using
tox -- --write <path-to-notebook>
and commit the results. If the notebook submits jobs, also use the argument--submit-jobs
. This means we can be sure all notebooks work and that users will see the same results when they run using the environment we recommend.To execute notebooks in a fixed Python environment, first install
tox
using pipx:You also need to install a few system dependencies: TeX, Poppler, and graphviz. On macOS, you can run
brew install mactex-no-gui poppler graphviz
. On Ubuntu, you can runapt-get install texlive-pictures texlive-latex-extra poppler-utils graphviz
.--write
argument.When you make a pull request changing a notebook that doesn’t submit jobs, you can get a version of that notebook that was executed by tox from CI. To do this, click “Show all checks” in the info box at the bottom of the pull request page on GitHub, then choose “Details” for the “Test notebooks” job. From the job page, click “Summary”, then download “Executed notebooks”. Otherwise, if your notebook does submit jobs, you need to run it locally using the steps mentioned earlier.
Ignore warnings in your notebook
We don’t want users to see warnings that can be avoided, so it’s best to fix the code to avoid them. However, if a warning is unavoidable, you can stop it blocking CI by adding an
ignore-warnings
tag to the cell. In VSCode, right-click the cell, choose “Add cell tag”, typeignore-warnings
, then press “Enter”. In Jupyter notebook (depending on version), choose View > Right Sidebar > Show Notebook Tools, then under “Common Tools” add a tag with textignore-warnings
.Add extra code checks to your notebook
Our CI checks notebooks run from start to finish without errors or warnings. You can add extra checks in notebooks to catch other unexpected behavior.
For example, say we claim a cell always returns the string
0011
. It would be embarassing if this was not true. We can assert this in CI by adding the following code cell, and hide it from users with aremove-cell
tag.In Jupyter notebooks, the underscore
_
variable stores the value of the previous cell output. You should also add a comment like# Confirm output is what we expect
so that authors know this block is only for testing. Make sure you add the tagremove-cell
. If something ever causes this value to change, CI will alert us.Lint notebooks
We use
squeaky
to lint our notebooks. First installtox
using pipx.To check if a notebook needs linting:
To fix problems in a notebooks, run:
Or, you can retrieve an executed and linted version of your notebook from CI following the steps at the end of the Execute notebooks section.
If you use the Jupyter notebook editor, consider adding squeaky as a pre-save hook. This will lint your notebooks as you save them, so you never need to worry about it.
Check for broken links
We have two broken link checkers: for internal links and for external links.
To check internal links:
To check external links:
Check for orphan pages
Every file should have a home in one of the
_toc.json
files.To check for orphaned pages, run:
Check page metadata
Every file needs to have a
title
anddescription
, as explained in Page Metadata Thelint
job in CI will fail with instructions for any bad file.You can also check for valid metadata locally:
Spellcheck
We use cSpell to check for spelling. The
lint
job in CI will fail if there are spelling issues.There are two ways to check spelling locally, rather than needing CI.
1.
Fixing false positives
There are two ways to deal with cSpell incorrectly complaining about a word, such as abbreviations.
scripts/config/cspell/dictionaries/people.txt
file. If it is a scientific or quantum specific word, add it to thescripts/config/cspell/dictionaries/qiskit.txt
file. If it doesn’t fit in either category, add it to thewords
section inscripts/config/cspell/cSpell.json
. The word is not case-sensitive.If the word appears in multiple files, prefer the second approach to add it to one of the dictionaries or
cSpell.json
.Check that pages render
It’s possible to write broken pages that crash when loaded. This is usually due to syntax errors.
To check that all the non-API docs render:
./start
by following the instructions at Preview the docs locallynpm run check:pages-render -- --non-api
You can also check that API docs render by using any of these arguments:
npm run check:pages-render -- --non-api --qiskit-release-notes --current-apis --dev-apis --historical-apis
. Warning that this is exponentially slower.CI will check on every PR that any changed files render correctly. We also run a weekly cron job to check that every page renders correctly.
Format README and TypeScript files
Run
npm run fmt
to automatically format the README,.github
folder, andscripts/
folder. You should run this command if you get the error in CIrun Prettier to fix
.To check that formatting is valid without actually making changes, run
npm run check:fmt
ornpm run check
.Regenerate an existing API docs version
This is useful when we make improvements to the API generation script.
You can regenerate all API docs versions following these steps:
main
usinggit checkout -b <branch-name>
.git status
and creating a new commit for them if necessary.npm run regen-apis
to regenerate all API docs versions forqiskit
,qiskit-ibm-runtime
, andqiskit-ibm-transpiler
.Each regenerated version will be saved as a distinct commit. If the changes are too large for one single PR, consider splitting it up into multiple PRs by using
git cherry-pick
orgit rebase -i
so each PR only has the commits it wants to target.If you only want to regenerate the latest stable minor release of each package, then add
--current-apis-only
as an argument, and in case you only want to regenerate versions of one package, then you can use the-p <pkg-name>
argument.Alternatively, you can also regenerate one specific version:
qiskit
,qiskit-ibm-runtime
, orqiskit-ibm-transpiler
) and its version.npm run gen-api -- -p <pkg-name> -v <version>
, e.g.npm run gen-api -- -p qiskit -v 0.45.0
If the version is not for the latest stable minor release series, then add
--historical
to the arguments. For example, use--historical
if the latest stable release is 0.45.* but you’re generating docs for the patch release 0.44.3.Additionally, If you are regenerating a dev version, then you can add
--dev
as an argument and the documentation will be built at/docs/api/<pkg-name>/dev
. For dev versions, end the--version
in-dev
, e.g.-v 1.0.0-dev
. If a release candidate has already been released, use-v 1.0.0rc1
, for example.In this case, no commit will be automatically created.
Generate new API docs
This is useful when new docs content is published, usually corresponding to new releases or hotfixes for content issues. If you’re generating a patch release, also see the below subsection for additional steps.
qiskit
,qiskit-ibm-runtime
, orqiskit-ibm-transpiler
) and its version.html_docs
.0.45.zip
for an artifact fromqiskit v0.45.2
.Copy shared link
buttonPeople with the link
and go toLink Settings
.Link Expiration
selectDisable Shared Link on
and set an expiration date of ~10 years into the future.Shared Link Settings
tab.scripts/config/api-html-artifacts.json
file, adding the new versions with the direct link from step 9.npm run gen-api -- -p <pkg-name> -v <version>
, e.g.npm run gen-api -- -p qiskit -v 0.45.0
If you are regenerating a dev version, then you can add
--dev
as an argument and the documentation will be built at/docs/api/<pkg-name>/dev
. For dev versions, end the--version
in-dev
, e.g.-v 1.0.0-dev
. If a release candidate has already been released, use-v 1.0.0rc1
, for example.In case you want to save the current version and convert it into a historical one, you can run
npm run make-historical -- -p <pkg-name>
beforehand.Generate patch releases
For example, if the current docs are for 0.45.2 but you want to generate 0.45.3.
Follow the same process above for new API docs, other than:
If the version is not for the latest stable minor release series, then add
--historical
to the arguments. For example, use--historical
if the latest stable release is 0.45.* but you’re generating docs for the patch release 0.44.3.View diff for
objects.inv
Since
objects.inv
is compressed, we can’t review changes throughgit diff
. Git does tell you if the file has changed, but this isn’t that helpful as the compressed file can be different even if the uncompressed contents are the same. If you want to see the diff for the uncompressed contents, first installsphobjinv
.The add the following to your
.gitconfig
(usually found at~/.gitconfig
).Dependabot - upgrade notebook testing version
When a new version of an API is released, we should also update
nb-tester/requirements.txt
to ensure that our notebooks still work with the latest version of the API. You can do this upgrade either manually or wait for Dependabot’s automated PR.Dependabot will fail to run at first due to not having access to the token. To fix this, have someone with write access trigger CI for the PR, such as by merging main or closing then reopening the issue.
You can land the API generation separately from the
requirements.txt
version upgrade. It’s high priority to get out new versions of the API docs ASAP, so you should not block that on the notebook version upgrade if you run into any complications like failing notebooks.Deploy guides & API docs
See the section “Syncing content with open source repo” in the internal docs repo’s README.
How to write the documentation
Refer to our style guide for technical writing guidance.
We use MDX, which is like normal markdown but adds extensions for custom components we have.
Refer to the Common Markdown syntax for a primer on Markdown. The below guide focuses on the other features you can use when writing docs.
How to add a new page
Choose which existing folder from
docs/
your new page belongs to (probablyguides
).Next, choose the file name. The file name will determine the URL. For example,
start/my-new-page.mdx
results in the URLstart/my-new-page
. Choose a file name that will be stable over the page’s lifespan and that is unlikely to clash with other topics. Use-
rather than_
as the delimiter. You can also ask for help choosing a name in the GitHub issue or pull request.If your file will have non-trivial code in it, please create a Jupyter notebook ending in
.ipynb
, rather than an MDX file. We prefer Jupyter notebooks when there is code because we have tests to make sure that the code still executes properly, whereas MDX is not tested.Add the file to these places:
_toc.json
, such asguides/_toc.json
. Thetitle
will show up in the left side bar. Note that theurl
leaves off the file extension.guides/map-problem-to-circuits
AND the Tools section in the_toc.json
file. Or, in the rare case that it doesn’t belong on any of these pages, list it inscripts/js/commands/checkPatternsIndex.ts
in the ALLOWLIST_MISSING_FROM_INDEX or the ALLOWLIST_MISSING_FROM_TOC section. For example,"/guides/qiskit-code-assistant"
.@NoNotifications
“Page metadata
Every page must set a
title
anddescription
:_toc.json
file.In MDX files, set the metadata at the top of the file like this:
In Jupyter notebooks, set
title
anddescription
in themetadata
section for the file. In VSCode, you can set up the metadata with these instructions:Links
Internal URLs referring to other docs pages should start with
/
and not include the file extension. For example:[Qiskit SDK](/api/qiskit)
[Bit ordering in the Qiskit SDK](/guides/bit-ordering)
External URLs should use the entire URL, such as
[GitHub](https://github.com)
.Images
Images are stored in the
public/images
folder. You should use subfolders to organize the files. For example, images forguides/my-file.mdx
should be stored likepublic/images/guides/my-file/img1.png
.To use the image:
To add an inline images:
To include a caption:
You can include a version of the image to be with the dark theme. You only need to create an image with the same name ending in
@dark
. So for example, if you have asampler.png
image, the dark version would besampler@dark.png
. This is important for images that have a white background.Videos
Videos are stored in the
public/videos
folder. You should use subfolders to organize the files. For example, images forguides/my-file.mdx
should be stored likepublic/videos/guides/my-file/video1.mp4
.To add a video:
Math
We use LaTeX to write math, which gets rendered by the library KaTeX.
Inline math expressions should start with
$
and end with$
, e.g.$\frac{123}{2}$
.Multi-line expressions should start with
$
and end with$
:Tables
Tables are supported: https://www.markdownguide.org/extended-syntax/.
Comments
Example comment:
{/* Comes from https://qiskit.org/documentation/partners/qiskit_ibm_runtime/getting_started.html */}
Collapsible sections
For content that you don’t want to show by default, use a collapsible section. The user will need to expand the section to read its contents. Refer to GitHub’s guide on
<details>
and<summary>
.Footnotes
Custom components
These are components that we expose through MDX. You can use them in both
.mdx
and.ipynb
files. In Jupyter notebooks, use Markdown cells.Admonitions
To use an
Admonition
, use the following syntaxAvailable types are
note, tip, info, caution, danger
. This is what they look like:By default, the title is the
type
capitalized. You can customize it by settingtitle
:Definition Tooltip
To use a
DefinitionTooltip
, use the following syntax:For full list of props, please check here.
Tabs
To use a
Tabs
component, use the following syntax:By default, the first tab is selected. You can change that by using the
defaultValue
prop.There are situations where you want to repeat the same tabs in several part of the page. In this situation, you can use the prop
group
to synchronize the selected tab in all usages.There is a specific use case where you want to show instructions for different operating systems. In this situation, you can replace the
Tabs
component by aOperatingSystemTabs
. The default value of the tab will be selected based on the user’s operating system.Proper marking and attribution
All information needs to identify, mark, and attribute IBM and applicable third-party trademarks. We do this the first time an IBM trademark appears on each page. See the Copyright and trademark information page for more details.
Some companies require a special attribution notice. View a list of the companies to include in a special attribution notice at the Special attributions section of the IBM Legal site.
A (non-exhaustive) list of trademarked names found in our docs:
Note: Although Qiskit is a registered trademark of IBM, we do not mark it as such.
See the Usage section of the IBM Quantum Experience Guide for guidance on when to use IBM and when to use IBM Quantum.
Trademark symbols
To create the symbols in markdown:
Use
®
to get ® for registered trademarks.use
™
to get ™ for nonregistered trademarks.⚠️ Note: Do not include trademarks in headings. The code will display rather than the symbol.