The documentation content home for https://docs.quantum.ibm.com (excluding API reference).
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:
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:
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:
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:
npm install
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. Run docker pull qiskit/documentation
to update to the latest version of the app.
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 up http://localhost:3000
, as explained in the prior section.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.
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:
pipx install tox
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 run apt-get install texlive-pictures texlive-latex-extra poppler-utils graphviz
.
tox
tox -- path/to/notebook.ipynb path/to/another-notbook.ipynb
--write
argument.
tox -- optional/paths/to/notebooks.ipynb --write
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.
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/nb-tester/notebooks.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
patching least_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
.
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", type ignore-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 text
ignore-warnings
.
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 a remove-cell
tag.
# Confirm output is what we expect.
assert _ == '0011'
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 tag remove-cell
.
If something ever causes this value to
change, CI will alert us.
We use squeaky
to lint our
notebooks. First install tox
using pipx.
pipx install tox
To check if a notebook needs linting:
# Check all notebooks in ./docs
tox -e lint -- docs/**/*.ipynb
To fix problems in a notebooks, run:
tox -e fix -- path/to/notebook
Or, you can retrieve an executed and linted version of your notebook from CI following the steps at the end of the Execute notebook 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.
We have two broken link checkers: for internal links and for external links.
To check internal links:
# Only check non-API docs
npm run check:internal-links
# You can add any of the below arguments to also check API docs.
npm run check:internal-links -- --current-apis --dev-apis --historical-apis --qiskit-release-notes
# However, `--historical-apis` currently has failing versions, so you may
# want to add `--skip-broken-historical`.
npm run check:internal-links -- --historical-apis --skip-broken-historical
# Or, run all the checks. Although this only checks non-API docs.
npm run check
To check external links:
# Specify the files you want after `--`
npm run check:external-links -- docs/run/index.md docs/run/circuit-execution.mdx
# You can also use globs
npm run check:external-links -- 'docs/run/*' '!docs/run/index.mdx'
Every file should have a home in one of the _toc.json
files. If for some reason a page should not have a home, add it to the ALLOWED_ORPHANS
list in scripts/checkOrphanPages.ts
.
To check for orphaned pages, run:
# Only check non-API docs
npm run check:orphan-pages
# You can also add any of the below arguments to check API docs
npm run check:orphan-pages -- --current-apis --dev-apis --historical-apis
# Or, run all the checks. However this will skip the API docs
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
# By default, only the non-API docs are checked. You can add any of the
# below arguments to also check API docs and/or translations.
npm run check:metadata -- --translations --apis
# Or, run all the checks. Although this only checks non-API docs.
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.
1.
# Only check spelling
npm run check:spelling
# Or, run all the checks
npm run check
There are two ways to deal with cSpell incorrectly complaining about a word, such as abbreviations.
{/* cspell:ignore hellllooooo, ayyyyy */}
# Hellllooooo!
Ayyyyy, this is a fake description.
cspell/dictionaries/people.txt
file. If it is a scientific or quantum specific word, add it to the cspell/dictionaries/qiskit.txt
file. If it doesn't fit in either category, add it to the words
section in 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
.
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 and translations render by using any of these arguments: npm run check:pages-render -- --non-api --qiskit-release-notes --current-apis --dev-apis --historical-apis --translations
. 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.
Run npm run fmt
to automatically format the README, .github
folder, and scripts/
folder. You should run this command if you get the error in CI run Prettier to fix
.
To check that formatting is valid without actually making changes, run npm run check:fmt
or npm run check
.
This is useful when we make improvements to the API generation script.
You can regenerate all API docs versions following these steps:
main
using git 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 for qiskit
, qiskit-ibm-provider
, qiskit-ibm-runtime
, and qiskit-transpiler-service
.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
or git 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-provider
, qiskit-ibm-runtime
, or qiskit-transpiler-service
) 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.
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-provider
, qiskit-ibm-runtime
, or qiskit-transpiler-service
) and its version.html_docs
.0.45.zip
for an artifact from qiskit v0.45.2
.Copy shared link
buttonPeople with the link
and go to Link Settings
.Link Expiration
select Disable Shared Link on
and set an expiration date of ~10 years into the future.Shared Link Settings
tab.scripts/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.
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.
objects.inv
Since objects.inv
is compressed, we can't review changes through git 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 install sphobjinv
.
pipx install sphobjinv
The add the following to your .gitconfig
(usually found at ~/.gitconfig
).
[diff "objects_inv"]
textconv = sh -c 'sphobjinv convert plain "$0" -'
This content lives on https://docs.quantum.ibm.com.
See the section "Syncing content with open source repo" in the internal docs repo's README.
This content lives on https://learning.quantum.ibm.com.
To deploy a file from the tutorials/
directory in this repository, see the instructions in the tutorials directory README.
To deploy a file from the ibm-quantum-learning-enablement repository, see the instructions in the internal tutorial repo's tutorials directory README.
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.
Choose which existing folder from docs/
your new page belongs to.
Next, choose the file name. The file name will determine the URL. For example, start/my-new-page.mdx
results in the URL start/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.
Once the file is created, you need to add metadata. Run npm run check:metadata
for instructions on how to do this. (Refer to Check file metadata)
Finally, add the file to the folder's _toc.json
, such as start/_toc.json
. The title
is what will show up in the left side bar. Note that the url
leaves off the file extension.
Images are stored in the public/images
folder. You should use subfolders to organize the files. For example, images for start/my-file.mdx
should be stored like public/images/start/my-file/img1.png
.
To use the image:
![Your image](/images/build/your-file/your_image.png)
To add an inline images:
Inline ![Inline image](/images/build/your-file/your_image.png) image
To include a caption:
![Your image](/images/build/your-file/your_image.png "Image 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 a sampler.png
image, the dark version would be sampler@dark.png
. This is important for images that have a white background.
Videos are stored in the public/videos
folder. You should use subfolders to organize the files. For example, images for start/my-file.mdx
should be stored like public/videos/start/my-file/video1.mp4
.
To add a video:
<video title="Write a description of the video here as 'alt text' for accessibility." className="max-w-auto h-auto" controls>
<source src="https://github.com/Qiskit/documentation/raw/main/videos/run/sessions/demo.mp4" type="video/mp4"></source>
</video>
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 $$
:
$$
L = \frac{123}{2} \rho v^2 S C_1s
$$
Tables are supported: https://www.markdownguide.org/extended-syntax/.
Example comment: {/_ Comes from https://qiskit.org/documentation/partners/qiskit_ibm_runtime/getting_started.html _/}
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>
.
Footnote 1 link[^first].
Footnote 2 link[^second].
Duplicated footnote reference[^second].
[^first]: Footnote **can have markup**
and multiple paragraphs.
[^second]: Second footnote text.
These are components that we expose through MDX. You can use them in both
.mdx
and .ipynb
files. In Jupyter notebooks, use Markdown cells.
To use an Admonition
, use the following syntax
<Admonition type="note">This is a __note__ example</Admonition>
Available 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 setting title
:
<Admonition type="note" title="Custom title">
This is a __note__ example
</Admonition>
To use a DefinitionTooltip
, use the following syntax:
<DefinitionTooltip definition="Definition for the Term">Term</DefinitionTooltip>
For full list of props, please check here.
You can use this component to render a circuit as it will be displayed in the composer. It does not have any interaction.
<Composer qasm={`
OPENQASM 2.0;
include "qelib1.inc";
qreg q[5];
creg c[5];
U(0, 0, pi / 2) q[0];
CX q[0], q[1];
u3(0, 0, pi /2) q[0];
u2(0, 0) q[0];
`}/>
To use a Tabs
component, use the following syntax:
<Tabs>
<TabItem value="pulses" label="Pulses">
This is the text for pulses
</TabItem>
<TabItem value="qasm" label="QASM">
This is the text for QASM
</TabItem>
</Tabs>
By default, the first tab is selected. You can change that by using the defaultValue
prop.
<Tabs defaultValue="qasm">
<TabItem value="pulses" label="Pulses">
This is the text for pulses
</TabItem>
<TabItem value="qasm" label="QASM">
This is the text for QASM
</TabItem>
</Tabs>
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.
<Tabs group="my-group">
<TabItem value="pulses" label="Pulses">
This is the text for pulses
</TabItem>
<TabItem value="qasm" label="QASM">
This is the text for QASM
</TabItem>
</Tabs>
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 a OperatingSystemTabs
. The default value of the tab will be selected based on the user's operating system.
<OperatingSystemTabs>
<TabItem value="mac" label="macOS">
Open a terminal and write the command
</TabItem>
<TabItem value="linux" label="Linux">
Open a terminal and write the command
</TabItem>
<TabItem value="win" label="Windows">
Go to windows/run and write `cmd`. It will open a command line. Execute this
command
</TabItem>
</OperatingSystemTabs>
This component show tabs with the Composer and the OpenQASM code. It also shows an Open in Composer link at the bottom.
<CircuitTabs name="Bell" qasm={`
OPENQASM 2.0;
include "qelib1.inc";
qreg q[2];
creg c[2];
reset q[0];
h q[0];
reset q[1];
cx q[0],q[1];
measure q[0] -> c[0];
measure q[1] -> c[1];
`}/>
To display a qasm operation (like a not gate), you can use the Operation
component:
<Operation name="x" />
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.
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.
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.