Part of https://github.com/Qiskit/documentation/issues/1043. Code Engine
is shut down tomorrow, so we need to turn off previews for now.
We're still working on what the replacement is. Once that's ready, we'll
revive whichever of these files are relevant.
Docs for https://pypi.org/project/qiskit-transpiler-service/.
These docs are not ready to go live to production yet. But we can safely
merge them in this repository to unblock infrastructure work in closed
source. We won't have closed source sync over these files until we get
the final okay from the transpiler service team.
This uses the approach discussed in #1174 to test notebooks that submit
jobs to IBM Quantum.
The script behaviour has changed a bit:
* We now have a list of `notebooks_no_mock`, these could include
notebooks with large circuits or that demonstrate features not available
on the fake backend. Future work could partially test these using the
approach in
[#1173](https://github.com/Qiskit/documentation/issues/1173).
* By default, it runs all notebooks except `notebooks_no_mock`, with the
patched package.
* `--submit-jobs` will run **all** notebooks, without the patched
package.
* `--only-unmockable` will run only `notebooks_no_mock`, without the
patched package.
The following notebooks do **not** work with this patch, but some of
them might not have worked anyway.
* `tutorials/variational-quantum-eigensolver/notebook.ipynb`
* `tutorials/submitting-transpiled-circuits/notebook.ipynb`
* `tutorials/build-repitition-codes/notebook.ipynb`
---------
Co-authored-by: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com>
Makes the notebook tester into an installable package so we can re-use
it in other repos.
Main changes are:
* Adding `pyproject.toml` and moving script to
`qiskit_docs_notebook_tester/__init__.py`
* Moving the lists of notebooks to a config file
* Splitting the requirements needed for running the code in the
notebooks form those neeed by the testing script itself
The interface via `tox` should be unaffected.
---------
Co-authored-by: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com>
Also explain what to install to get the notebooks working locally.
Tested on macOS Apple Silicon. The Linux requirements come from CI but
weren't tested locally.
Compiling a list of the most common fixes we make when editing
documentation, for the curious author who might want a reference.
---------
Co-authored-by: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com>
Co-authored-by: Rebecca Dimock <66339736+beckykd@users.noreply.github.com>
We have a couple more features available via cell tags. See diff for an
explanation.
---------
Co-authored-by: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com>
Closes https://github.com/Qiskit/documentation/issues/74.
We were finally able to get a Docker image working with Code Engine.
Turns out the problem was upgrading from Next.js 13.4 to 13.5 because
Code Engine does not play nicely with 13.4.13 or newer.
The Docker image was so slow because we were under-allocating resources.
We double the resources. It's still somewhat slow, but less laggy than
before. The next step would be to double again, which costs more money,
so I was thinking to start with this for now?
---------
Co-authored-by: Frank Harkins <frankharkins@hotmail.co.uk>
Close#388
I ended up not using `zxMain` and set a few different options for
choosing which api docs to look through (similar to
`checkPagesRender.ts`). @Eric-Arellano Let me know if there's anything
that needs fixed or should be refactored!
---------
Co-authored-by: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com>
This PR adds instructions on setting up Git to use
[`sphobjinv`](https://github.com/bskinn/sphobjinv) to display diffs for
`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.
Git will default back to binary diff if it doesn't find a rule in
`.gitconfig` so adding `.gitattributes` shouldn't disrupt contributors
that don't follow the guide.
Hopefully this information will help keep more eyes on the file and spot
any unintended changes.
Here's an example of it in action (downgrading qiskit to 0.46):
<img width="950" alt="Screenshot 2024-03-05 at 14 20 04"
src="https://github.com/Qiskit/documentation/assets/36071638/5aabaca4-d175-4871-84c5-e583069e0c1a">
It's confusing when `./start` diverges from `docs.quantum.ibm.com`.
We now warn every time when running `./start`:
```
❯ ./start
Warning: this may be using an outdated version of the app. Run `docker pull qiskit/documentation` to check for updates.
WARNING: The requested image's platform (linux/amd64) does not match the detected host platform (linux/arm64/v8) and no specific platform was requested
▲ Next.js 14.0.1
- Local: http://f9e8103d2cee:3000
- Network: http://172.17.0.2:3000
✓ Ready in 1377ms
[remoteRefresh] server is listening at port 5001
```
I debated always running `docker pull qiskit/documentation`
automatically, but I think it's too slow and annoying.
Closes https://github.com/Qiskit/documentation/issues/876.
This split brings several improvements:
1. Simpler internal link checker code.
2. The external link checker now deduplicates links across all files,
which avoids repeating requests.
3. The external link checker logs its progress every 20 links.
4. It's possible to check external links without checking internal
links.
We run the external link checker in our weekly cron job over all files,
other than translations and historical Qiskit versions. That change was
added in https://github.com/Qiskit/documentation/pull/913.
Uses squeaky to lint notebooks.
While this has some minor benefits (removing empty cells etc.), it will
become much more useful when we switch notebook outputs to SVG.
Closes https://github.com/Qiskit/documentation/issues/793.
This unblocks us starting to check API docs in
https://github.com/Qiskit/documentation/issues/66. It also speeds up the
workflow for non-API docs, which is valuable because non-API and API
docs have such different workflows.
I only added an `--apis` argument rather than e.g. `--current-apis` vs
`--historical-apis` because this check is fast enough to not need the
nuance.
---------
Co-authored-by: Arnau Casau <47946624+arnaucasau@users.noreply.github.com>
Closes#726
The first instance on a page of every trademarked name (whether IBM or
third-party) should be marked with the trademark symbol (except in
headings, where the code will not render as a symbol).
Outstanding questions: Where does the trademark symbol occur if the
following are the first instance on a page?:
(editing to add: preliminary guidance directs us as follows: )
- [ ] IBM Quantum™ systems
- [ ] Qiskit® Runtime service
- [ ] Qiskit® Runtime
- [ ] Qiskit IBM Provider (still unknown)
- [ ] Qiskit® Patterns
- [ ] Qiskit® Experiments
- [ ] Qiskit® 1.0
- [ ] Qiskit® Runtime IBM Client
- [ ] Qiskit® Runtime IBM REST API
- [ ] IBM Quantum™ Network
References:
https://www.ibm.com/brand/experience-guides/quantum/voice#usagehttps://www.ibm.com/legal/copyright-trademark
### Progress
- [x] Migration guides
- [x] Start
- [x] Build
- [x] Transpile
- [x] Verify
- [x] Run
- [x] Support
---------
Co-authored-by: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com>
This PR adds support to generate dev versions for the API generation
script.
For the moment, the automatic regeneration will not take into account
dev versions to keep this PR easy to review. I'll add support for that
in a follow-up, together with the documentation of the dev versions.
Part of #316
---------
Co-authored-by: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com>
### Summary
Thanks to #737, the API generation script doesn't need an argument to
specify the CI artifact URL used in the generation. Because of that, we
can automatize the script to regenerate all API docs in the repository.
### New command
The PR adds a new command `regen-apis` where we can regenerate multiple
versions of our three APIs with one command:
```bash
npm run regen-apis
```
By default, all minor releases of each API will be regenerated, but we
can add the `--current-apis-only` argument to regenerate only the latest
stable versions.
```bash
npm run regen-apis -- --current-apis-only
```
Alternatively, you can regenerate only one of the three available APIs.
We can use the `-p` argument, which could be combined with the other
arguments, similarly to the API generation script:
```bash
npm run regen-apis -- -p <pkg-name>
```
### Git instructions
To run the script, we need to create a dedicated branch and have a clean
git status. The script will create a commit per version regenerated and
the developers can git cherry-pick them how they want to create
different PRs.
If the regeneration fails for a specific version, the script will call
`git restore` to avoid mixing changes from two different versions when
regenerating the next one.
### Output
At the end of each call to the new command, we will see a summarization
of all versions regenerated with three different possible outcomes per
version:
<table style="width:100%">
<tr>
<th>Possible Output</th>
<th>Meaning</th>
<th>Creates a new commit</th>
<th>Restores the files</th>
</tr>
<tr>
<td>✅ <pkg-name> <version> regenerated correctly</td>
<td>The regeneration was successful</td>
<td>Yes</td>
<td>No</td>
</tr>
<tr>
<td>☑️ <pkg-name> <version> is up-to-date</td>
<td>The regeneration was successful, but no files were modified</td>
<td>No</td>
<td>No</td>
</tr>
<tr>
<td>❌ <pkg-name> <version> failed to regenerate</td>
<td>The regeneration failed</td>
<td>No</td>
<td>Yes</td>
</tr>
</table>
Closes#720
---------
Co-authored-by: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com>
Part of #719
This PR modifies the API generation script to download the CI artifacts
stored in the Box folder https://ibm.ent.box.com/folder/246867649571 and
removes the `-a <artifact-url>` argument.
The PR also renames the old `scripts/lib/api/downloadCIArtifacts.ts` to
`scripts/lib/api/apiArtifacts.ts` to make it more generic, and it
removes the associated test. The test file only was related to the `-a`
argument that was removed.
---------
Co-authored-by: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com>
Closes https://github.com/Qiskit/documentation/issues/511. Example:
```
$ npm run check-pages-render
Checked 10 / 71 pages
Checked 20 / 71 pages
Checked 30 / 71 pages
Checked 40 / 71 pages
Checked 50 / 71 pages
Checked 60 / 71 pages
Checked 70 / 71 pages
✅ All pages render without crashing
```
## Only checks non-API docs by default
This script is quite slow, at least on my M1 because the Docker images
is built with x86.
So, to avoid CI slowing down too much, we only check non-API pages in PR
builds. Our nightly cron job checks everything else.
## Does not auto-start Docker
We no longer have the file `webServer.ts` thanks to
https://github.com/Qiskit/documentation/pull/578, which was a great
improvement.
Rather than adding back somewhat complex code for us to auto-start the
server—and then to periodically ping if it's ready or time out—we expect
the user to start up the server. That's acceptable since usually people
will rely on CI to run this check. It's too slow for people to be
frequently running locally.
---------
Co-authored-by: Frank Harkins <frankharkins@hotmail.co.uk>
Part of https://github.com/Qiskit/documentation/issues/495. We now will
enforce in CI that historical API docs are valid for Runtime and
Provider. To do this, this PR adds the `--skip-broken-historical`
argument.
In a follow up, I want to try checking Qiskit docs, at least certain
versions. But I'm waiting until we regenerate the docs with
https://github.com/Qiskit/documentation/pull/552 applied because I
suspect it will fix some issues.
This unblocks https://github.com/Qiskit/documentation/issues/495. We
still have to actually fix the broken links, but we can at least now
detect them.
To make the script more interactive, we now output a description of each
file batch, like this:
```
Checking links for non-API docs
Checking links for qiskit-ibm-runtime v0.14
❌ docs/api/qiskit-ibm-runtime/0.14/ibm-runtime.md: Could not find link 'runtime_service' ❓ Did you mean '/api/qiskit-ibm-runtime/0.14/ibm-runtime'?
❌ docs/api/qiskit-ibm-runtime/0.14/qiskit_ibm_runtime.QiskitRuntimeService.md: Could not find link '/api/qiskit/providers_models'
Checking links for qiskit-ibm-runtime v0.15
❌ docs/api/qiskit-ibm-runtime/0.15/ibm-runtime.md: Could not find link 'runtime_service' ❓ Did you mean '/api/qiskit-ibm-runtime/0.15/ibm-runtime'?
❌ docs/api/qiskit-ibm-runtime/0.15/qiskit_ibm_runtime.QiskitRuntimeService.md: Could not find link '/api/qiskit/providers_models'
```
Note that to fix the broken links, we're going to need to set `toLoad`
for some of the projects. For example, you can see in the above
`qiskit-ibm-runtime` failures that they need to read in the file
`/api/qiskit/providers_models`. I plan to address that in a follow up
because we want to load the minimum amount of files possible to reduce
memory usage, so I still want to see what we really need to load.
---------
Co-authored-by: Arnau Casau <47946624+arnaucasau@users.noreply.github.com>
Part of https://github.com/Qiskit/documentation/issues/495.
--
This PR adds two arguments to `npm run check:links`, `--current-apis`
and `--qiskit-release-notes`. In a follow up, we'll add
`--historical-apis`. By default, we don't do any of these checks since
it's pretty rare for a PR author to be changing those files and we want
`npm run check` to be as fast as possible locally. CI will still check
the whole thing, though.
This makes the script around 2x faster:
```
npm run check:links 4.04s user 0.32s system 156% cpu 2.797 total
npm run check:links -- --current-apis --qiskit-release-notes 8.66s user 0.99s system 134% cpu 7.182 total
```
--
To fix the actual broken links, I manually fixed problems in release
notes up to 0.44. We are unlikely to regenerate these release notes, so
manual fixes should be fine.
I did not fix 0.45, though, since we will continue to regenerate those
release notes per https://github.com/Qiskit/documentation/pull/537. We
will need to fix the underlying problem in the API docs, or in our API
generation script.
Part of https://github.com/Qiskit/documentation/issues/476.
This PR sets up two GitHub actions for interfacing with Crowdin.com, the
website the translation team uses for translations.
1. Upload English sources. We do this on any change to `docs/` (except
API docs), which the translation team so that they can start making
updates sooner. For example:
<img width="346" alt="Screenshot 2023-12-20 at 5 45 05 PM"
src="https://github.com/Qiskit/documentation/assets/14852634/0ed4cbed-45db-45bb-9150-5d90bec7a0f6">
2. Download the translations. This happens once a week, which the
translations team requested. It will open up a pull request like
https://github.com/Eric-Arellano/documentation/pull/10.
## How auth works
We only need to set GitHub Secrets for CROWDIN_PROJECT_ID and
CROWDIN_PERSONAL_TOKEN. GitHub will automatically set GITHUB_TOKEN using
[this
mechanism](https://docs.github.com/en/actions/security-guides/automatic-token-authentication).
## Translations saved at `translations/` folder
This adds a top-level `translations/` folder, rather than nesting the
translations inside the `docs/` folder. For example:
<img width="367" alt="Screenshot 2023-12-20 at 5 48 09 PM"
src="https://github.com/Qiskit/documentation/assets/14852634/42e27fd4-5c67-4ceb-aae3-8f25315f7aae">
This top-level folder is useful because it reduces noise in the `docs/`
folder. It makes it more obvious to the team what is the original source
docs vs. what is translations and should not be modified directly in
this repository.
### How this works with the app
To get docs previews working in this repo, we teach the Docker image to
mount `translations/` as if its contents were in the folder `docs/`,
since the application expects all content to live there.
When we sync the translations from open-source to closed-source for
production, we will copy the contents of `translations/` so that it
actually lives underneath `docs/`. For example,
`translations/es/support.mdx` becomes `docs/es/support.mdx`.
## Locales
As explained in https://github.com/Qiskit/documentation/issues/7, we
generally want to use the two-letter code for languages, like `es` and
`fr`. The only exception is Chinese, where we need to distinguish
between Traditional and Simplified.
This config works with that, so long as in Crowdin.com, the project sets
up this Language Mapping under the Languages settings:
<img width="475" alt="Screenshot 2023-12-20 at 5 59 19 PM"
src="https://github.com/Qiskit/documentation/assets/14852634/adf643d1-716a-435c-9e32-9762c6570956">
## Doesn't yet add `_languages.json`
As explained in https://github.com/Qiskit/documentation/issues/7, we
will probably want a file like `_languages.json` that teaches the docs
app what each language is, such as its name to show in the language
toggle. That schema still needs to be finalized and it can be added in a
follow up.
Adds a GitHub action to test notebook code examples on pull request.
### Handling notebooks that submit jobs
We only want to submit jobs to IBM Quantum _very_ rarely (such as
updating notebook outputs once per qiskit release), but runtime doesn't
have a way of restricting the types of job you can send.
In this PR, I've limited cell execution to 100s. This should be short
enough to do most local tasks and to get backend information, but not
nearly long enough for a job to run on the open provider (usually takes
hours).
If someone accidentally makes a PR with a notebook that submits jobs,
the script will timeout and raise an error. On exit, the script cancels
any jobs created since it started running. This means they won't take up
any resources, and the author will be alerted when CI fails.
---------
Co-authored-by: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com>
Co-authored-by: Arnau Casau <47946624+arnaucasau@users.noreply.github.com>
Closes https://github.com/Qiskit/documentation/issues/367.
@axelhzf had written an excellent guide for how to work with MDX in the
closed source repository, but it wasn't copied over here when docs moved
to open source.
This PR:
* Copies over Axel's guide with some small tweaks
* Adds guidance on adding a new page, including how to choose between
MDX vs. Jupyter and how to name the file
* Mentions collapsible sections
---------
Co-authored-by: Axel Hernández Ferrera <axelhzf@gmail.com>
Co-authored-by: Arnau Casau <47946624+arnaucasau@users.noreply.github.com>
Co-authored-by: abbycross <across@us.ibm.com>
Closes#311.
It adds a new method to generate the API docs using a CI artifact. The
script has a new mandatory argument `--artifact` or `-a` to specify a
link to a specific artifact we want to download. This change is
necessary because we can't use qiskit.org anymore.
To be able to download the artifacts, we need to have installed and
configured the [GitHub command
line](https://docs.github.com/en/github-cli/github-cli/quickstart).
Example of a generation for the Qiskit 0.45 API docs using an artifact:
`npm run gen-api -- -p qiskit -v 0.45.0 -a
https://github.com/Qiskit/qiskit/suites/17881600359/artifacts/1026798160`
This PR adds a script to automatically execute notebooks in CI.
To keep PRs small and focussed, this only adds the scripts to test
notebooks, it doesn't actually fix those notebooks or add anything to
CI.
<details>
<summary>Example: Success</summary>
</details>
<details>
<summary>Example: Failure</summary>
</details>
<details>
<summary>Why <code>tox</code>?</summary>
An important feature is to be able to run a single notebook in the
virtual environment. With `tox`, we can use commands like this:
```sh
tox -- path/to/notebook
```
Whereas with `nox`, this is the simplest I could get it:
```sh
nox --session 'test(path="path/to/notebook")'
```
Note this also doesn't autocomplete the path.
The main reason for choosing `nox` seems to be more flexible
configuration, but we only need simple configuration in this repo so
this isn't a problem.
</details>
***
Part of #166
---------
Co-authored-by: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com>
Please, have a look whenever possible. @Eric-Arellano
All occurrences where quantum-computing.ibm.com have been changed to
quantum.ibm.com , leaving subdomains untouched.
EDIT:
I did git pull upstream before creating this branch, now I see there are
some conflicts, maybe there was a merge while I was creating this PR?
We need a method to convert the current API into a historical version,
and for this purpose, we can use the new `convertApiDocsToHistorical.ts`
script using the `make-historical` new command. This command expects an
argument specifying the name of the API we want to switch over. For
example:
> npm run make-historical -- -p qiskit
This feature is useful for `qiskit-ibm-runtime` and `qiskit-ibm-povider`
since they don't publish more than one documentation version.
Moreover, using this new tool, this PR adds back version 0.14 of
qiskit-ibm-runtime into a subfolder in the project.
Closes#332
This PR replaces any qiskit.org links with 1XP or github equivalents.
Need to wait to merge until I can update the deprecation policy and
maintainer guide links after
https://github.com/Qiskit/qiskit/pull/11218/ merges.
This should partially resolve#297 , however for the api links we'll
need to make updates for those directly in the repos where the API refs
live (maybe this is beyond the scope of the original issue?)
---------
Co-authored-by: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com>
First part of https://github.com/Qiskit/documentation/issues/332. A
follow up will generate historical versions prior to Qiskit 0.44; this
PR is focused on the general infrastructure.
See https://github.com/Qiskit/documentation/issues/8 for the overall of
the folder structure.
Users can now run `npm run gen-api -- -p qiskit -v 0.44.0 --historical`.
Runtime and Provider aren't supported since they need
https://github.com/Qiskit/documentation/issues/332.
## How links work
We still use relative links for API cross-references. That works because
the links will be relative to the current directory, whether that is
`0.44/` or the unversioned top-level folder.
However, images use absolute links. We decided to have dedicated folders
for images for each API, rather than sharing a common folder. That is
because images may change throughout API versions and we don't want to
risk merge conflicts.
## Release notes
Per https://github.com/Qiskit/documentation/issues/330, every API
version should have identical release notes. We decided that's desirable
UI.
So, this PR copies the top-level release notes when adding a new
historical version. That implements the first part of #330; now we only
need a script that validates the release notes are all in sync, and also
a way to have updates to the top-level release notes automatically
update the subfolders.
---------
Co-authored-by: Arnau Casau <47946624+arnaucasau@users.noreply.github.com>
Co-authored-by: Arnau Casau <arnaucasau@gmail.com>
Closes#368.
It adds the following features:
- A method to skip complete folders using glob patterns.
- A daily cron job to validate all the internal and external links.
- Validation of the release notes by default
The CI test has been changed to validate only internal links. The
motivation behind this is we want the CI to be fast, and also, the
validation of external links can make it fail due to fetch errors for
external reasons that have nothing to do with the correctness of the
link. Regardless, we still want to validate external links, and a new
daily test has been added to check all the external links.
Closes https://github.com/Qiskit/documentation/issues/339.
It wasn't intentional that we didn't have `index.md` files and instead
used `/runtime_service` and `/ibm_provider`. It was only because that's
what the original qiskit.org docs do, and I don't think we realized that
was bad and we should fix it.
This PR does mean `/runtime_service` and `/ibm_provider` will now 404. I
couldn't find any references to those pages outside of our own docs, so
it didn't seem necessary to set up redirects. But I can if we think it's
important.
Eric Arellano