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.
### Summary
This PR adds support for the validation of external links using the link
checker. Tests for the validation have been included, and the CI test
has been extended to validate external links.
By default, the link checker only validates internal links, but we can
activate the external links validation using:
`npm run check:links -- --external`
Closes#305
---------
Co-authored-by: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com>
First part of adding historical API versions
(https://github.com/Qiskit/documentation/issues/77).
There were two issues with us trying to auto-compute the version:
1. It didn't work reliably. The logic looked for the latest GitHub
release, but that doesn't account for patch releases and pre-releases.
For example, if the current stable version is 0.44, but we just
pre-released 0.45.0b1, then the script would set the version as 0.45.0b1
2. We can't deduce the version anymore when we're generating for
historical versions. We need the developer to tell us what they want.
While it's a little more verbose to have to say the version, we're not
running this script super frequently. It's not a big deal imo.
## CLI args vs a config file
Originally, I was considering if we'd want a config file that had all
the versions of a package. I realized that's not very useful because it
wouldn't be clear what the script should generate. Most the time, we
don't want to regenerate historical API docs, which is slow.
## Script is now one-package-at-a-time
You can no longer generate API docs in one run for all 3 packages. That
allows us to make the CLI interface simple.
In my experience, this matches how we use the script. I usually only
wanted to regenerate a specific package after a release.
Relates to https://github.com/Qiskit/documentation/issues/6, which is
about docs. This PR only adds Prettier to our support code. We might
want to extend Prettier to docs in a follow up.
Having a consistent format is convenient and saves us time so that
humans don't have to manually move things around.
We have a non-trivial amount of TypeScript tooling, so this is worth
adding imo.
- Add ignore list
- Also ignore files in `docs/api`
- Add `npm run check:links` command
- Add to CI
- Update README
---------
Co-authored-by: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com>
The content team requested this as a useful tool to show how the docs
are rendering on `main`, before the content gets synced to close source
and pushed to production.
This uses the same IBM Cloud Engine code we use for PR previews. It
doesn't use GitHub Pages because we need to run the server with Docker,
whereas GH Pages expects a simple static website.
The staging link should be stable at
https://qiskit-docs-preview-staging.1799mxdls7qz.us-south.codeengine.appdomain.cloud.
In the closed source repository that consumes Qiskit/docs, we have this
same check for valid file metadata. It is useful to run it here too so
that we fail more eagerly.
Like the internal code, this uses TypeScript. It makes the code more
readable and better aligned with the internal code.
---------
Co-authored-by: Axel Hernández Ferrera <axelhzf@gmail.com>
Closes https://github.com/Qiskit/docs/issues/3. We use the same open
source workflow we use with qiskit.org and qiskit-sphinx-theme.
We only preview the docs for PRs built directly on this repository, not
for forks. That is a security restriction due to how forks work.
Closes https://github.com/Qiskit/docs/issues/1. Running `./start` will
open up the One Docs app at localhost:3000 using content from the local
repository.
Currently, you have to log into IBM Cloud and have the correct
permissions. We will improve this with
https://github.com/Qiskit/docs/issues/53.
---------
Co-authored-by: Axel Hernández Ferrera <axelhzf@gmail.com>
Co-authored-by: Luciano Bello <bel@zurich.ibm.com>
Closes https://github.com/Qiskit/docs/issues/5.
This sets up some initial infrastructure for the repository, like CI and
the folder structure from @axelhzf's proof of concept of how to open
source documentation content.
Follow up PRs will build on this infrastructure as part of
https://github.com/Qiskit/docs/milestone/1.
## Synchronizing cSpell config with closed source
This PR copies the closed source config for cSpell.
It's a bummer that this config is duplicated. I considered if we should
automate synchronizing the config file, which would need to be the
closed source repo pulling in the closed source file, since the open
source repo cannot access the closed source repo. But I think it's not
worth the complexity to automate this, at least for now.
The closed source repository will open up a PR to use a new version of
this qiskit/docs repository. That PR will run its own spellcheck. So if
there is new content with typos, the spellcheck will fail, which is a
signal that we need to update the closed source cSpell config.
If this ends up not being sustainable, then I recommend we figure out
how to automate syncing. But for now, keep it simple.
---------
Co-authored-by: Axel Hernández Ferrera <axelhzf@gmail.com>
Co-authored-by: Eric Harvey <eric@harvey.io>
abbycross