` component","sha":"aede12f52af5b0faab6a51c5fb22fcdac1bf0318","created_at":"2025-05-23 20:11","time_from_now":"1个月前","created_at_unix":1748002309}},{"name":"style-guide.md","path":"style-guide.md","sha":"b369eccfe7634d07a2fec361cf33c37e69c97a71","type":"file","submodule_git_url":null,"size":5203,"is_readme_file":0,"content":null,"target":null,"commit":{"message":"Revamp README by creating a separate MDX guide (#2772)\n\nOur README has gotten pretty overwhelming. This PR tries to improve it\nby splitting into three guides:\n\n* README.md\n - entry point\n - how to install the project\n - how to run checks\n* mdx-guide.md: how to write MDX & set up new pages\n* style-guide.md: guidance on things like tone\n\nThis also adds guidance on how to have platform-specific pages, which\nwas written by `@frankharkins` in closed source.\n\n---------\n\nCo-authored-by: Frank Harkins \nCo-authored-by: Abby Cross \nCo-authored-by: Rebecca Dimock <66339736+beckykd@users.noreply.github.com>","sha":"a5d070d4896d7b1495ba587744cab0d4f8ae557c","created_at":"2025-03-14 03:45","time_from_now":"4个月前","created_at_unix":1741895139}},{"name":"tox.ini","path":"tox.ini","sha":"c1e7ea6f5056ee8c07db6dcec119fd78a6b5a345","type":"file","submodule_git_url":null,"size":988,"is_readme_file":null,"content":null,"target":null,"commit":{"message":"Update testing env to include `PendingDeprecation` warnings (#3114)\n\nCloses #2716 \n\nAccording to the official python docs, `PendingDeprecation` warnings are\n[ignored by\ndefault](https://docs.python.org/3/library/exceptions.html#PendingDeprecationWarning)\nunless [Python Development\nMode](https://docs.python.org/3/library/devmode.html) is enabled (done\neither through the `-Xdev` or `-Wd` flags when invoking `python` or by\nsetting the environment variable `PYTHONDEVMODE=1`).\n\nThis PR sets the `tox` environment to run using dev mode with the\n`PYTHONDEVMODE` env var.","sha":"9b4e19266887f610b104f811deda8df2822e28fa","created_at":"2025-05-13 23:39","time_from_now":"2个月前","created_at_unix":1747150747}},{"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":"11个月前","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%3A21262%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%2Fquantum.cloud.ibm.com%2Fdocs%20and%20https%3A%2F%2Fdocs.quantum.ibm.com%20(excluding%20API%20reference).%5Cn%5CnRefer%20to%3A%5Cn%5Cn-%20Our%20%5BMDX%20guide%5D(.%2Fmdx-guide.md)%20for%20how%20to%20write%20documentation%20and%20use%20our%20variant%20of%20markdown.%5Cn-%20Our%20%5Bstyle%20guide%5D(.%2Fstyle-guide.md)%20for%20technical%20writing%20guidance.%5Cn%5Cn%23%23%23%20Licensing%5Cn%5CnThis%20repository%20is%20dual-licensed%20to%20distinguish%20between%20code%20and%20content.%5Cn%5Cn-%20Code%20(including%20scripts%2C%20source%20files%2C%20and%20code%20snippets%20in%20documentation%20examples)%20is%20licensed%20under%20the%20Apache%20License%202.0%2C%20please%20review%20the%20%60LICENSE%60%20file%20for%20more%20information%5Cn-%20Content%20(including%20guides%2C%20tutorials%2C%20courses%2C%20media%2C%20and%20other%20non-code%20assets)%20is%20licensed%20under%20the%20Creative%20Commons%20Attribution-ShareAlike%204.0%20International%20(CC%20BY-SA%204.0)%2C%20please%20review%20the%20%60LICENSE-DOCS%60%20file%20for%20more%20information.%5Cn%5Cn%23%23%20Improving%20IBM%20Quantum%20and%20Qiskit%20documentation%5Cn%5CnMaintaining%20up-to-date%20documentation%20is%20a%20huge%20challenge%20for%20any%20software%20project%2C%20but%20especially%20for%20a%20field%20like%20quantum%20computing%2C%20because%20advances%20in%20new%20research%20and%20technological%20capabilities%20come%20at%20a%20fast%20pace.%20As%20a%20result%2C%20we%20greatly%20appreciate%20anyone%20who%20takes%20the%20time%20to%20support%20us%20in%20keeping%20this%20content%20accurate%20and%20up%20to%20the%20highest%20quality%20standard%20possible%2C%20to%20benefit%20the%20broadest%20range%20of%20users.%5Cn%5CnRead%20on%20for%20more%20information%20about%20how%20to%20support%20this%20project%3A%5Cn%5Cn%23%23%23%20Best%20ways%20to%20contribute%20to%20documentation%5Cn%5Cn%23%23%23%23%201.%20Report%20bugs%2C%20inaccuracies%2C%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%26reg%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%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%20%5Bnew%20content%20request%20issue%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%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%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%2Fquantum.cloud.ibm.com%2Fdocs%2Fen%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%23%20Set%20up%20this%20repository%5Cn%5Cn%23%23%23%20Git%20clone%20tip%5Cn%5CnThis%20repository%20is%20very%20large%2C%20so%20it%20is%20slow%20to%20clone%20the%20first%20time.%20We%20recommend%20instead%20using%20the%20argument%20%60--filter%3Dblob%3Anone%60%3A%5Cn%5Cn%60%60%60bash%5Cngit%20clone%20--filter%3Dblob%3Anone%20https%3A%2F%2Fgithub.com%2FQiskit%2Fdocumentation.git%5Cn%60%60%60%5Cn%5Cn%60--filter%3Dblob%3Anone%60%20means%20that%20Git%20will%20_lazily_%20download%20file%20contents%20when%20you%20need%20them%2C%20rather%20than%20eagerly%20downloading%20everything%20on%20the%20initial%20clone.%5Cn%5CnWe%20also%20recommend%20running%20this%20command%20once%20to%20tell%20Git%20to%20ignore%20the%20%60gh-pages%60%20branch%2C%20which%20is%20solely%20used%20for%20PR%20previews%20and%20is%20very%20large%3A%5Cn%5Cn%60%60%60bash%5Cngit%20config%20--add%20remote.origin.fetch%20'%5Erefs%2Fheads%2Fgh-pages'%5Cn%60%60%60%5Cn%5Cn%23%23%23%20Prerequisites%20to%20building%20the%20docs%20locally%5Cn%5CnWe%20provide%20several%20tools%20to%20preview%20the%20documentation%20locally%20and%20to%20run%20quality%20checks.%20While%20many%20of%20these%20tools%20run%20in%20your%20PR%20through%20CI%2C%20we%20recommend%20installing%20them%20locally%20for%20faster%20iteration.%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.%5Cn3.%20%5BTox%5D(https%3A%2F%2Ftox.wiki%2F)%20to%20run%20Python%20tools.%5Cn%20%20%20-%20We%20recommend%20using%20%5Bpipx%5D(https%3A%2F%2Fpipx.pypa.io%2Fstable%2F)%2C%20which%20is%20a%20tool%20to%20install%20Python%20programs%20while%20keeping%20your%20Python%20installation%20clean.%20After%20installing%20pipx%2C%20use%20%60pipx%20install%20tox%60.%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%20%20%20-%20On%20Windows%2C%20run%20%60python%20start%60%20instead.%20Alternatively%2C%20use%20Windows%20Subsystem%20for%20Linux%20and%20run%20%60.%2Fstart%60.%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%5CnMaintainers%3A%20when%20you%20release%20a%20new%20version%20of%20the%20image%2C%20you%20need%20to%20update%20the%20image%20digest%20in%20%60.%2Fstart%60%20by%20following%20the%20instructions%20at%20the%20top%20of%20the%20file%20and%20opening%20a%20pull%20request.%5Cn%5Cn%23%23%23%20Tip%3A%20Periodically%20prune%20Docker%5Cn%5CnOccasionally%2C%20Docker%20might%20fail%20when%20it%20runs%20out%20of%20disk%20space.%20For%20example%2C%20you%20might%20encounter%20an%20error%20like%20this%3A%5Cn%5Cn%60%60%60%5CnENOSPC%3A%20no%20space%20left%20on%20device%2C%20mkdir%20'%2Ftmp%2Fxfs-4d1dfe51'%5Cn%60%60%60%5Cn%5CnTry%20running%20%60docker%20system%20prune%60%20to%20clear%20Docker's%20system%20space.%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%20Run%20quality%20checks%5Cn%5CnWe%20use%20multiple%20tools%20to%20ensure%20that%20documentation%20meets%20high%20standards.%20These%20tools%20will%20run%20automatically%20in%20your%20PR%20through%20CI%2C%20but%20it%20is%20much%20faster%20to%20run%20the%20checks%20locally.%5Cn%5CnUse%20%60.%2Ffix%60%20to%20automatically%20apply%20fixes%2C%20like%20fixing%20formatting.%20Warning%3A%20we%20cannot%20automatically%20fix%20every%20problem%2C%20so%20you%20should%20also%20run%20%60.%2Fcheck%60%20afterwards.%5Cn%5Cn%60%60%60sh%5Cn.%2Ffix%5Cn%60%60%60%5Cn%5CnUse%20%60.%2Fcheck%60%20to%20validate%20that%20there%20are%20no%20issues.%20If%20you%20encounter%20an%20error%2C%20fix%20it%20by%20following%20the%20instructions%20in%20the%20error%20message%2C%20then%20keep%20running%20%60.%2Fcheck%60%20and%20fixing%20any%20errors%20until%20it%20fully%20passes%20without%20any%20error.%5Cn%5Cn%60%60%60sh%5Cn.%2Fcheck%5Cn%60%60%60%5Cn%5CnOn%20Windows%2C%20run%20%60python%20fix%60%20and%20%60python%20check%60%20instead.%20Alternatively%2C%20use%20Windows%20Subsystem%20for%20Linux%20and%20run%20%60.%2Ffix%60%20and%20%60.%2Fcheck%60.%5Cn%5Cn%23%23%23%20VSCode%3A%20optional%20extensions%5Cn%5CnYou%20may%20find%20it%20convenient%20to%20install%20the%20following%20VSCode%20extensions%20to%20automatically%20run%20some%20of%20our%20tools.%20Setting%20up%20these%20extensions%20is%20optional.%5Cn%5Cn-%20For%20Jupyter%20notebooks%2C%20add%20the%20tool%20'squeaky'%20as%20a%20%5Bpre-save%5Cn%20%20hook%5D(https%3A%2F%2Fgithub.com%2Ffrankharkins%2Fsqueaky%3Ftab%3Dreadme-ov-file%23jupyter-pre-save-hook).%5Cn%20%20This%20will%20fix%20and%20lint%20your%20notebooks%20when%20you%20save%20them.%5Cn-%20%5BCode%20Spell%20Checker%5D(https%3A%2F%2Fmarketplace.visualstudio.com%2Fitems%3FitemName%3Dstreetsidesoftware.code-spell-checker)%5Cn%5Cn%23%23%23%20Advanced%3A%20run%20additional%20checks%5Cn%5CnWe%20offer%20some%20tools%20that%20are%20not%20included%20in%20%60.%2Fcheck%60%20and%20%60.%2Ffix%60.%20Likewise%2C%20many%20of%20the%20checks%20skip%20API%20docs%20by%20default.%5Cn%5CnRun%20%60npm%20run%60%20to%20see%20a%20list%20of%20all%20our%20checks.%20For%20any%20particular%20check%2C%20run%20%60npm%20run%20my-check%20--%20--help%60%20for%20more%20information%20and%20advanced%20arguments%2C%20such%20as%20%60npm%20run%20check%3Ametadata%20--%20--help%60.%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%5CnIf%20you%20don't%20do%20this%20step%2C%20you%20will%20get%20the%20error%20%5C%22FAILED%20scripts%2Fnb-tester%2Ftest%2Ftest_notebook_classification.py%3A%3Atest_all_notebooks_are_classified%5C%22.%5Cn%5Cn%23%23%23%20Add%20package%20version%20information%5Cn%5CnAdd%20a%20new%20markdown%20cell%20under%20your%20title%20with%20a%20%60version-info%60%20tag.%5CnWhen%20you%20execute%20the%20notebook%20(see%20the%20next%20section)%2C%20the%20script%20will%20populate%5Cnthis%20cell%20with%20the%20package%20versions%20so%20users%20can%20reproduce%20the%20results.%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--%20%3Cpath%2Fto%2Fnotebook.ipynb%3E%20%3Cpath%2Fto%2Fanother-notebook.ipynb%3E%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%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.%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.%2C%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(e.g.%20%60qiskit%60%20or%20%60qiskit-ibm-runtime%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%20e.g.%20%60npm%20run%20gen-api%20--%20-p%20qiskit%20-v%200.45.0%60.%20If%20it%20is%20not%20the%20latest%20minor%20version%2C%20set%20%60--historical%60.%5Cn%5CnFor%20dev%20docs%2C%20add%20%60--dev%60%20and%20either%20use%20a%20version%20like%20%60-v%201.0.0-dev%60%20or%20%60-v%201.0.0rc1%60.%5Cn%5Cn%23%23%23%20Setting%20up%20a%20new%20minor%20version%5Cn%5CnFor%20example%2C%20the%20latest%20unversioned%20docs%20were%20%600.2.0%60%20but%20%600.3.0%60%20was%20just%20released.%5Cn%5CnYou%20must%20first%20save%20the%20latest%20unversioned%20docs%20as%20historical%20docs%20by%20running%20%60npm%20run%20gen-api%60%20with%20the%20%60--historical%60%20arg.%20For%20example%2C%20first%20run%20%60npm%20run%20gen-api%20--%20-p%20qiskit%20-v%200.2.0%20--historical%60.%5Cn%5CnOnce%20the%20historical%20docs%20are%20set%20up%2C%20you%20can%20now%20generate%20the%20newest%20docs%20by%20following%20the%20normal%20process%2C%20such%20as%20%60npm%20run%20gen-api%20--%20-p%20qiskit%20-v%200.3.0%60.%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%5CnWhen%20uploading%20the%20artifact%20to%20Box%2C%20overwrite%20the%20existing%20file%20with%20the%20new%20one.%20No%20need%20to%20update%20the%20file%20metadata.%5Cn%5CnIf%20the%20version%20is%20not%20for%20the%20latest%20stable%20minor%20release%20series%2C%20remember%20to%20add%20%60--historical%60%20to%20the%20arguments.%20For%20example%2C%20use%20%60--historical%60%20if%20the%20latest%20stable%20release%20is%200.3.%5C%5C*%20but%20you're%20generating%20docs%20for%20the%20patch%20release%200.2.1.%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%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%22%2C%22sha%22%3A%227b919e6f3d82026afc00adc5f0564370b39c2eca%22%2C%22replace_content%22%3A%22%23%20Qiskit%20documentation%5Cn%5CnThe%20documentation%20content%20home%20for%20https%3A%2F%2Fquantum.cloud.ibm.com%2Fdocs%20and%20https%3A%2F%2Fdocs.quantum.ibm.com%20(excluding%20API%20reference).%5Cn%5CnRefer%20to%3A%5Cn%5Cn-%20Our%20%5BMDX%20guide%5D(%2Fscnc%2Fqiskit-documentation%2Ftree%2Fmain%2Fmdx-guide.md)%20for%20how%20to%20write%20documentation%20and%20use%20our%20variant%20of%20markdown.%5Cn-%20Our%20%5Bstyle%20guide%5D(%2Fscnc%2Fqiskit-documentation%2Ftree%2Fmain%2Fstyle-guide.md)%20for%20technical%20writing%20guidance.%5Cn%5Cn%23%23%23%20Licensing%5Cn%5CnThis%20repository%20is%20dual-licensed%20to%20distinguish%20between%20code%20and%20content.%5Cn%5Cn-%20Code%20(including%20scripts%2C%20source%20files%2C%20and%20code%20snippets%20in%20documentation%20examples)%20is%20licensed%20under%20the%20Apache%20License%202.0%2C%20please%20review%20the%20%60LICENSE%60%20file%20for%20more%20information%5Cn-%20Content%20(including%20guides%2C%20tutorials%2C%20courses%2C%20media%2C%20and%20other%20non-code%20assets)%20is%20licensed%20under%20the%20Creative%20Commons%20Attribution-ShareAlike%204.0%20International%20(CC%20BY-SA%204.0)%2C%20please%20review%20the%20%60LICENSE-DOCS%60%20file%20for%20more%20information.%5Cn%5Cn%23%23%20Improving%20IBM%20Quantum%20and%20Qiskit%20documentation%5Cn%5CnMaintaining%20up-to-date%20documentation%20is%20a%20huge%20challenge%20for%20any%20software%20project%2C%20but%20especially%20for%20a%20field%20like%20quantum%20computing%2C%20because%20advances%20in%20new%20research%20and%20technological%20capabilities%20come%20at%20a%20fast%20pace.%20As%20a%20result%2C%20we%20greatly%20appreciate%20anyone%20who%20takes%20the%20time%20to%20support%20us%20in%20keeping%20this%20content%20accurate%20and%20up%20to%20the%20highest%20quality%20standard%20possible%2C%20to%20benefit%20the%20broadest%20range%20of%20users.%5Cn%5CnRead%20on%20for%20more%20information%20about%20how%20to%20support%20this%20project%3A%5Cn%5Cn%23%23%23%20Best%20ways%20to%20contribute%20to%20documentation%5Cn%5Cn%23%23%23%23%201.%20Report%20bugs%2C%20inaccuracies%2C%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%26reg%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%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%20%5Bnew%20content%20request%20issue%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%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%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%2Fquantum.cloud.ibm.com%2Fdocs%2Fen%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%23%20Set%20up%20this%20repository%5Cn%5Cn%23%23%23%20Git%20clone%20tip%5Cn%5CnThis%20repository%20is%20very%20large%2C%20so%20it%20is%20slow%20to%20clone%20the%20first%20time.%20We%20recommend%20instead%20using%20the%20argument%20%60--filter%3Dblob%3Anone%60%3A%5Cn%5Cn%60%60%60bash%5Cngit%20clone%20--filter%3Dblob%3Anone%20https%3A%2F%2Fgithub.com%2FQiskit%2Fdocumentation.git%5Cn%60%60%60%5Cn%5Cn%60--filter%3Dblob%3Anone%60%20means%20that%20Git%20will%20_lazily_%20download%20file%20contents%20when%20you%20need%20them%2C%20rather%20than%20eagerly%20downloading%20everything%20on%20the%20initial%20clone.%5Cn%5CnWe%20also%20recommend%20running%20this%20command%20once%20to%20tell%20Git%20to%20ignore%20the%20%60gh-pages%60%20branch%2C%20which%20is%20solely%20used%20for%20PR%20previews%20and%20is%20very%20large%3A%5Cn%5Cn%60%60%60bash%5Cngit%20config%20--add%20remote.origin.fetch%20'%5Erefs%2Fheads%2Fgh-pages'%5Cn%60%60%60%5Cn%5Cn%23%23%23%20Prerequisites%20to%20building%20the%20docs%20locally%5Cn%5CnWe%20provide%20several%20tools%20to%20preview%20the%20documentation%20locally%20and%20to%20run%20quality%20checks.%20While%20many%20of%20these%20tools%20run%20in%20your%20PR%20through%20CI%2C%20we%20recommend%20installing%20them%20locally%20for%20faster%20iteration.%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.%5Cn3.%20%5BTox%5D(https%3A%2F%2Ftox.wiki%2F)%20to%20run%20Python%20tools.%5Cn%20%20%20-%20We%20recommend%20using%20%5Bpipx%5D(https%3A%2F%2Fpipx.pypa.io%2Fstable%2F)%2C%20which%20is%20a%20tool%20to%20install%20Python%20programs%20while%20keeping%20your%20Python%20installation%20clean.%20After%20installing%20pipx%2C%20use%20%60pipx%20install%20tox%60.%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%20%20%20-%20On%20Windows%2C%20run%20%60python%20start%60%20instead.%20Alternatively%2C%20use%20Windows%20Subsystem%20for%20Linux%20and%20run%20%60.%2Fstart%60.%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%5CnMaintainers%3A%20when%20you%20release%20a%20new%20version%20of%20the%20image%2C%20you%20need%20to%20update%20the%20image%20digest%20in%20%60.%2Fstart%60%20by%20following%20the%20instructions%20at%20the%20top%20of%20the%20file%20and%20opening%20a%20pull%20request.%5Cn%5Cn%23%23%23%20Tip%3A%20Periodically%20prune%20Docker%5Cn%5CnOccasionally%2C%20Docker%20might%20fail%20when%20it%20runs%20out%20of%20disk%20space.%20For%20example%2C%20you%20might%20encounter%20an%20error%20like%20this%3A%5Cn%5Cn%60%60%60%5CnENOSPC%3A%20no%20space%20left%20on%20device%2C%20mkdir%20'%2Ftmp%2Fxfs-4d1dfe51'%5Cn%60%60%60%5Cn%5CnTry%20running%20%60docker%20system%20prune%60%20to%20clear%20Docker's%20system%20space.%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%20Run%20quality%20checks%5Cn%5CnWe%20use%20multiple%20tools%20to%20ensure%20that%20documentation%20meets%20high%20standards.%20These%20tools%20will%20run%20automatically%20in%20your%20PR%20through%20CI%2C%20but%20it%20is%20much%20faster%20to%20run%20the%20checks%20locally.%5Cn%5CnUse%20%60.%2Ffix%60%20to%20automatically%20apply%20fixes%2C%20like%20fixing%20formatting.%20Warning%3A%20we%20cannot%20automatically%20fix%20every%20problem%2C%20so%20you%20should%20also%20run%20%60.%2Fcheck%60%20afterwards.%5Cn%5Cn%60%60%60sh%5Cn.%2Ffix%5Cn%60%60%60%5Cn%5CnUse%20%60.%2Fcheck%60%20to%20validate%20that%20there%20are%20no%20issues.%20If%20you%20encounter%20an%20error%2C%20fix%20it%20by%20following%20the%20instructions%20in%20the%20error%20message%2C%20then%20keep%20running%20%60.%2Fcheck%60%20and%20fixing%20any%20errors%20until%20it%20fully%20passes%20without%20any%20error.%5Cn%5Cn%60%60%60sh%5Cn.%2Fcheck%5Cn%60%60%60%5Cn%5CnOn%20Windows%2C%20run%20%60python%20fix%60%20and%20%60python%20check%60%20instead.%20Alternatively%2C%20use%20Windows%20Subsystem%20for%20Linux%20and%20run%20%60.%2Ffix%60%20and%20%60.%2Fcheck%60.%5Cn%5Cn%23%23%23%20VSCode%3A%20optional%20extensions%5Cn%5CnYou%20may%20find%20it%20convenient%20to%20install%20the%20following%20VSCode%20extensions%20to%20automatically%20run%20some%20of%20our%20tools.%20Setting%20up%20these%20extensions%20is%20optional.%5Cn%5Cn-%20For%20Jupyter%20notebooks%2C%20add%20the%20tool%20'squeaky'%20as%20a%20%5Bpre-save%5Cn%20%20hook%5D(https%3A%2F%2Fgithub.com%2Ffrankharkins%2Fsqueaky%3Ftab%3Dreadme-ov-file%23jupyter-pre-save-hook).%5Cn%20%20This%20will%20fix%20and%20lint%20your%20notebooks%20when%20you%20save%20them.%5Cn-%20%5BCode%20Spell%20Checker%5D(https%3A%2F%2Fmarketplace.visualstudio.com%2Fitems%3FitemName%3Dstreetsidesoftware.code-spell-checker)%5Cn%5Cn%23%23%23%20Advanced%3A%20run%20additional%20checks%5Cn%5CnWe%20offer%20some%20tools%20that%20are%20not%20included%20in%20%60.%2Fcheck%60%20and%20%60.%2Ffix%60.%20Likewise%2C%20many%20of%20the%20checks%20skip%20API%20docs%20by%20default.%5Cn%5CnRun%20%60npm%20run%60%20to%20see%20a%20list%20of%20all%20our%20checks.%20For%20any%20particular%20check%2C%20run%20%60npm%20run%20my-check%20--%20--help%60%20for%20more%20information%20and%20advanced%20arguments%2C%20such%20as%20%60npm%20run%20check%3Ametadata%20--%20--help%60.%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%5CnIf%20you%20don't%20do%20this%20step%2C%20you%20will%20get%20the%20error%20%5C%22FAILED%20scripts%2Fnb-tester%2Ftest%2Ftest_notebook_classification.py%3A%3Atest_all_notebooks_are_classified%5C%22.%5Cn%5Cn%23%23%23%20Add%20package%20version%20information%5Cn%5CnAdd%20a%20new%20markdown%20cell%20under%20your%20title%20with%20a%20%60version-info%60%20tag.%5CnWhen%20you%20execute%20the%20notebook%20(see%20the%20next%20section)%2C%20the%20script%20will%20populate%5Cnthis%20cell%20with%20the%20package%20versions%20so%20users%20can%20reproduce%20the%20results.%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--%20%3Cpath%2Fto%2Fnotebook.ipynb%3E%20%3Cpath%2Fto%2Fanother-notebook.ipynb%3E%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%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.%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.%2C%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(e.g.%20%60qiskit%60%20or%20%60qiskit-ibm-runtime%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%20e.g.%20%60npm%20run%20gen-api%20--%20-p%20qiskit%20-v%200.45.0%60.%20If%20it%20is%20not%20the%20latest%20minor%20version%2C%20set%20%60--historical%60.%5Cn%5CnFor%20dev%20docs%2C%20add%20%60--dev%60%20and%20either%20use%20a%20version%20like%20%60-v%201.0.0-dev%60%20or%20%60-v%201.0.0rc1%60.%5Cn%5Cn%23%23%23%20Setting%20up%20a%20new%20minor%20version%5Cn%5CnFor%20example%2C%20the%20latest%20unversioned%20docs%20were%20%600.2.0%60%20but%20%600.3.0%60%20was%20just%20released.%5Cn%5CnYou%20must%20first%20save%20the%20latest%20unversioned%20docs%20as%20historical%20docs%20by%20running%20%60npm%20run%20gen-api%60%20with%20the%20%60--historical%60%20arg.%20For%20example%2C%20first%20run%20%60npm%20run%20gen-api%20--%20-p%20qiskit%20-v%200.2.0%20--historical%60.%5Cn%5CnOnce%20the%20historical%20docs%20are%20set%20up%2C%20you%20can%20now%20generate%20the%20newest%20docs%20by%20following%20the%20normal%20process%2C%20such%20as%20%60npm%20run%20gen-api%20--%20-p%20qiskit%20-v%200.3.0%60.%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%5CnWhen%20uploading%20the%20artifact%20to%20Box%2C%20overwrite%20the%20existing%20file%20with%20the%20new%20one.%20No%20need%20to%20update%20the%20file%20metadata.%5Cn%5CnIf%20the%20version%20is%20not%20for%20the%20latest%20stable%20minor%20release%20series%2C%20remember%20to%20add%20%60--historical%60%20to%20the%20arguments.%20For%20example%2C%20use%20%60--historical%60%20if%20the%20latest%20stable%20release%20is%200.3.%5C%5C*%20but%20you're%20generating%20docs%20for%20the%20patch%20release%200.2.1.%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%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%22%7D"},"zoneReducer":{"zoneDetail":"","newsDetail":""}}