I keep getting tripped up on all the places we need to list new files.
Adding that information here in hopes of saving all those failed builds!
---------
Co-authored-by: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com>
This is to unblock https://github.com/Qiskit/documentation/issues/495.
Our goal is to fix all broken links for Qiskit 0.46+, whereas we don't
plan to fix <0.46. So, we want our script to make it ergonomic to check
0.46+.
This PR results in us now checking 0.46, 1.0, and 1.1 docs. It does that
with two changes:
1. Rename `--skip-broken-historical` to `--include-broken-historical` so
that, by default, `--historical-apis` "just works".
1. `--qiskit-release-notes` is renamed to
`--qiskit-legacy-release-notes`.
- It now only checks <0.46.
- `--current-apis` will check the release notes for the latest version,
whereas before you had to remember to specify `--qiskit-release-notes`
- For Qiskit 0.46+, `--historical-apis` will check the release note for
each version, whereas before you had to remember to specify
`--qiskit-release-notes`
| Option | Checks |
|--------------------------------:|:--------------------------------------------------------|
| `--current-apis` | Current API docs, including latest Qiskit release
note |
| `--qiskit-legacy-release-notes` | Only Qiskit release notes < 0.46 |
| `--historical-apis` | All Runtime and Transpiler historical; Qiskit
0.46+, including those release notes |
| `--historical-apis --include-broken-historical` | All historical,
including Qiskit historical release notes |
Follow up to https://github.com/Qiskit/documentation/pull/1917. That
resulted in some pages having their behavior fixed, so we can be more
strict in our API lints.
This PR also makes some bigger improvements to the checks:
* Runs `check:metadata` in CI, thanks to a new allowlist
* Simplifies `check:orphan-pages` to have an `--apis` arg
* DRYs our ignore list for `check:internal-links`
Part of https://github.com/Qiskit/documentation/issues/1870. We'll set
up redirects in closed source from `qiskit-transpiler-service/*` to
`qiskit-ibm-transpiler/*`.
We don't yet generate `qiskit-ibm-transpiler` version 0.5 because that
is going to require a new set of more specific redirects, as the page
names will change from `qiskit_transpiler_service.Foo` to
`qiskit_ibm_transpiler.Foo`. That'll be done in a follow up after this
initial migration is complete.
We were being inconsistent with calling Runtime "Qiskit Runtime IBM
Client" but "Qiskit IBM Runtime REST API". We also don't use IBM with
"Qiskit Transpiler Service Client" and "Qiskit SDK". So, `@jyu00` and
`@javabster` proposed that we simplify to remove the redundant IBM.
This PR updates the left page titles we use. A closed source PR will
update the top dropdown.
We don't update the index pages for Runtime API docs because those are
auto-generated.
Closes https://github.com/Qiskit/documentation/issues/1756. While this
sometimes results in annoying false positives, we decided it was worth
it to us.
For notebooks, we only check the source code we write, not the output
generated.
The preview app is slow due because the it searches through the docs
folder each time we load a page. Eric had the idea to improve the speed
by removing API docs from the image. Since the API docs are so large,
this roughly halves the time taken per page load. Writers can ask to
include API docs using the `--apis` option.
Helps with https://github.com/Qiskit/documentation/issues/1720.
---------
Co-authored-by: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com>
This is meant to better split config files vs source code, to make it
more obvious what should be changed by everyday script users.
Not all of the scripts use `config/` yet, but could be refactored in the
future if we want.
This PR removes tutorial notebooks and related tools as they're being
moved to a closed-source repository.
---------
Co-authored-by: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com>
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>
Rebecca Dimock