The documentation content home for https://docs.quantum-computing.ibm.com. Note this repo does not contain content for https://learning.quantum-computing.ibm.com/ or https://qiskit.org. Refer to https://github.com/Qiskit/qiskit to make changes to the docs at https://qiskit.org/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:
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:
- For problems you've found in the Qiskit API Reference section, open an issue in the Qiskit repo here.
- For problems you've found in the Qiskit Runtime IBM Client section, open an issue in the Qiskit IBM Runtime repo here.
- For problems you've found in any other section of docs, open a content bug issue here.
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.
You can help the team prioritize already-open issues by doing the following:
- For bug reports, leave a comment in the issue if you have also been experiencing the same problem and can reproduce it (include as much information as you can, e.g., browser type, Qiskit version, etc.).
- For new content requests, leave a comment or upvote (๐) in the issue if you also would like to see that new content added.
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:
- Read the Code of Conduct
- Check for open, unassigned issues with the "good first issue" label
- Select an issue that is not already assigned to someone and leave a comment to request to be assigned
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:
- Check that you have addressed all the requirements from the original issue
- Run the spell checker
- Use the GitHub "fixes" notation to link your PR to the issue you are addressing
These tools will also run in CI, but it can be convenient when iterating to run the tools locally.
First, install the below software:
- Node.js. If you expect to use JavaScript in other projects, consider using NVM. Otherwise, consider using Homebrew or installing Node.js directly.
- Docker. You must also ensure that it is running.
- You can use Colima or Rancher Desktop. When installing Rancher Desktop, choose Moby/Dockerd as the engine, rather than nerdctl. To ensure it's running, open up the app "Rancher Desktop".
Then, install the dependencies with:
npm install
Run ./start
in your terminal, then open http://localhost:3000/start in your browser.
The local preview does not include the initial index page and the top nav bar from docs.quantum-computing.ibm.com. Therefore, you must directly navigate in the URL to the folder that you want:
- http://localhost:3000/build
- http://localhost:3000/start
- http://localhost:3000/run
- http://localhost:3000/transpile
- http://localhost:3000/verify
- http://localhost:3000/api/qiskit
- http://localhost:3000/api/qiskit-ibm-runtime
- http://localhost:3000/api/qiskit-ibm-provider
- http://localhost:3000/api/migration-guides
Contributors with write access to this repository can use live previews of the docs: GitHub will deploy a website using your changes.
To use live previews, push your branch to upstream
rather than your fork. GitHub will leave a comment with the link to the site. Please prefix your branch name with your initials, e.g. EA/fix-build-typo
, for good Git hygiene.
We also re-deploy the docs every time we merge into main
at the site https://qiskit-docs-preview-staging.1799mxdls7qz.us-south.codeengine.appdomain.cloud.
This staging environment can be useful to see how the docs are rendering before we push it live to production.
CI will check for broken links. You can also check locally:
# Only check for internal broken links
npm run check:links
# Enable the validation of external links
npm run check:links -- --external
# Or, run all the checks
npm run check
Every file needs to have a title
and description
. The lint
job in CI will fail with instructions for any bad file.
You can also check for valid metadata locally:
# Only check file metadata
npm run check:metadata
# Or, run all the checks
npm run check
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.
# Only check spelling
npm run check:spelling
# Or, run all the checks
npm run check
- Use the VSCode extension Code Spell Checker.
There are two ways to deal with cSpell incorrectly complaining about a word, such as abbreviations.
- Ignore the word in the local markdown file by adding a comment to the file, like below. The word is not case-sensitive, and the comment can be placed anywhere.
{/* cspell:ignore hellllooooo, ayyyyy */}
# Hellllooooo!
Ayyyyy, this is a fake description.
- Add the word to the file
cSpell.json
in thewords
section. The word is not case-sensitive.
If the word appears in multiple files, prefer the second approach to add it to cSpell.json
.
Run npm run fmt
to automatically format MDX files.
To check that formatting is valid without actually making changes, run npm run check:fmt
or npm run check
.
- Choose which documentation you want to regenerate:
qiskit
,qiskit-ibm-provider
, orqiskit-ibm-runtime
- Determine the current version of the published stable documentation, e.g. at https://qiskit.org/documentation/
- Run
npm run gen-api -- -p <pkg-name> -v <version>
, e.g.npm run gen-api -- -p qiskit -v 0.45.0