Closes https://github.com/Qiskit/documentation/issues/745. This follows
the spec laid out there:
* Do nothing if the dev version is an rc
* Otherwise, use GitHub API to get latest artifact from `main`
* Update `api-html-artifacts.json` to the GitHub URL
* Generate the docs
* Create a PR if there were changes
To be able to call `updateApiDocs.ts` from `syncDevDocs.ts`, we now use
the special value ``if (import.meta.url === `file://${process.argv[1]}`)
``, which is like Python's `if __name__ == "__main__":` so that you can
import the file without executing the script. This works because we use
ES6 modules now.
---------
Co-authored-by: Frank Harkins <frankharkins@hotmail.co.uk>
Closes https://github.com/Qiskit/documentation/issues/495.
We are checking every Runtime and qiskit-ibm-transpiler version, plus
Qiskit 0.46+. This PR makes it more explicit and precise which links we
have to ignore to get that green. That reduces the risk of false
positives.
This PR also now has the external link checker check every single Qiskit
version, whereas before it skipped historical links. It's important we
don't have 404s, even for old docs. Note that the external link checker
doesn't check GitHub source code links, which makes this change much
less expensive.
The remaining issues are tracked by
https://github.com/Qiskit/documentation/issues/1938.
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`
The artifact upload was failing because `path` was set to the empty
string. It's fine to give an invalid file path like `no-changes`, so
long as we give something. The action will warn but not fail in this
case.
Closes https://github.com/Qiskit/documentation/issues/1826.
## Switches to Python 3.11
Qiskit Serverless requires Python 3.11+ now, even though Qiskit SDK
still supports 3.9 and 3.10. While I'm talking to the Serverless team,
it seems very unlikely they are going to change their mind on this due
to their own constraints.
Unfortunately, this means that we need to always use Python 3.11 with
our repository so that we can install serverless for the files that use
it. Our other alternative is to stop testing the files with Serverless,
but that seems even worse.
The risk with using 3.11 in CI rather than 3.9 is that we may use syntax
not in Python 3.9 and 3.10. However, given the actual history of our
docs, this seems unlikely: we don't use new Python syntax like type
hints. If we do use Python 3.11-syntax, it's not the end of the world.
## Tests all notebooks on changes to requirements.txt
This was an oversight that we would not test the notebooks when changing
requirements.txt. So, we merged a change that worked locally but broke
CI. Now, we test all notebooks when the nb-tester program and config
changes.
## Also upgrades Runtime
This is necessary to make Serverless happy. According to
https://docs.quantum.ibm.com/api/qiskit-ibm-runtime/release-notes#0270-2024-08-08,
there are no breaking changes. CI also shows everything passes.
Don't waste resources.
From [GH Action's
documentation](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#onpushpull_requestpull_request_targetpathspaths-ignore):
> If you want to both include and exclude path patterns for a single
event, use the paths filter prefixed with the ! character to indicate
which paths should be excluded.
>
> The order that you define paths patterns matters:
>
> - A matching negative pattern (prefixed with !) after a positive match
will exclude the path.
> - A matching positive pattern after a negative match will include the
path again.
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>
Some projects are going to start using our JS scripts soon. To help us
with packaging the scripts, this PR bundles all of the JS into
`scripts/js` whereas before it was spread out over `scripts/commands`
and `scripts/lib`.
Beyond packaging the scripts, I think this is a cleaner organization
anyways to differentiate between our three scripts projects:
* `js`
* `nb-tester`
* `pr-previews` (renamed from `pr_previews`)
(In a follow up, we might want to centralize all of our config into
`scripts/config`)
A PR preview failed to deploy today because a prior workflow was already
pushing the deploy, which messed up the Git state. We should only ever
attempt to deploy one PR preview at a time - pushing a new commit should
cancel the prior deploy attempt if still in progress.
To cancel, this uses the technique from
https://www.meziantou.net/how-to-cancel-github-workflows-when-pushing-new-commits-on-a-branch.htm.
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>
Adds a script and action to delete PR previews for closed PRs. See
ce7e3fbbe7 for an example.
---------
Co-authored-by: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com>
This is necessary to get Next.js to use the correct links for loading
CSS/JS files and for links to other HTML files. Otherwise, it uses links
like `/my-file` which go to `qiskit.github.io/my-file` rather than
`qiskit.github.io/documentation/pr-x/my-file`.
Part of https://github.com/Qiskit/documentation/issues/1043.
This deploys a new folder at
https://qiskit.github.io/documentation/pr-{x}. For now, it's a contrived
`index.html` only to get the technique working. We will switch to the
full built preview app once the Docker image is accessible.
The GitHub workflow follows this logic:
1. Build the static site
2. Deploy by pushing the files to the `gh-pages` branch under the folder
`pr-{x}`
3. Check if the deploy has worked by polling
https://qiskit.github.io/documentation/pr-{x}, with a one minute
timeout.
A follow up will add the cleanup mechanism.
---------
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
The requirements for the learning uploader have changed since it was
first created.
It was originally intended to be used locally by writers to quickly push
content to the platform. I wrote it in Python so writers would not need
to install node, and using string manipulations to interact with the
REST API was good enough for just uploading the zip and linking the new
file. It also included functionality for a writer to log into the
database through a CLI.
Now, the uploader is only used in CI, so we don't care about logging in
or sticking to Python, and we want to be able to do more complex
manipulations such as adding new lessons and changing metadata. For this
reason, this PR rewrites the uploader using the official [Directus
SDK](https://docs.directus.io/guides/sdk/), which makes interacting with
the API a lot easier.
---------
Co-authored-by: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com>
Co-authored-by: Arnau Casau <47946624+arnaucasau@users.noreply.github.com>
Co-authored-by: Abby Mitchell <23662430+javabster@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.
Closes https://github.com/Qiskit/documentation/issues/1299
This PR adds a script that validates that every page shows up both in
the Tools folders and in the Workflow index pages.
---------
Co-authored-by: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com>
Closes#1554
Removing Abby M as an automatic assignee from bug reports too.
After the docs reorg, can reword the title of the bug issue for Platform
docs by indicating it's for anything in the /guides/ directory.
---------
Co-authored-by: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com>
Part of #1462
This PR prepares our checks for the guides migration to get green CI
when we make the change. Changes:
- Added API docs links to `ignore.ts`. Those links need to be updated
from the other repos and from the Box artifacts for historical versions.
Once the migration is done we'll have redirects set up for those links
as explained
[here](https://github.com/Qiskit/documentation/issues/1461).
- Added some words to the cspell dictionary and fixed other complaints
from the checker
- Added a script to fix the Qiskit bot files by changing the paths to
`guides/`. The PR also changes the ignores we had to `guides/`, leaving
the old ones that should be removed once the migration is done.
- Fixed the `update_internal_links.py` script to switch over more links
and consider the migration guides.
- Added entries for the notebooks with their names on the `guides/`
folder. Once the migration is done, we need to remove the old ones.
Each time the fortnightly cron job runs, I usually make a PR updating
the notebooks in this repo with the output of the cron job. This PR
automates that process. As well as saving some manual work, this also
means I can review those PRs too.
See https://github.com/frankharkins/documentation/pull/10 for an example
of this working.
Should fix 1034.
## Investigation
It seems PR previews _are_ being cleaned up correctly for _merged_ PRs;
the teardown action is running, and the previews are no longer
accessible after merging (see following screenshot as example).
<img width="300" alt="Screenshot 2024-06-07 at 13 35 48"
src="https://github.com/Qiskit/documentation/assets/36071638/0066b309-9432-4213-81bd-1836521a8900">
It seems the problem is if a PR is closed but not merged (e.g. #1468,
#1380, and #1289 still have active previews). I believe this is the
reason:
https://github.com/orgs/community/discussions/26657#discussioncomment-3252753.
## Solution
This PR tries to fix this by using the `pull_request_target` event to
trigger teardowns. This should trigger correctly when PRs are closed.
We need to be careful with this event as it allows untrusted PRs to
trigger events using secrets. Since this action runs on the target
branch (rather than a merge commit of the target and PR branches), an
untrusted user shouldn't be able to do anything malicious, but we need
to make sure we **never** checkout the PR branch with this event type,
or read any user-defined inputs (such as the PR title) as it could lead
to an injection. I think this is unlikely, but I've left a warning in
the action just in case.
See https://github.com/frankharkins/documentation/pull/7 for a
demonstration. The "Preview teardown" step ran after the PR was closed.
We want to run the notebook classification check on every PR. This PR
pulls that test out into a separate pytest suite and runs it as part of
the standard CI job. I'd like to also add some more tests to this suite
as the `nb-tester` has grown in complexity and there were some issues
with it recently.
Suggestion on how to handle notebook testing on forks. Resolves#967.
This PR proposes always failing the test on forks, with advice to merge
to another branch in this repo to test it before merging to the main
branch. While a little clunky, we very rarely get PRs from forks so this
is probably simplest for now. We can review the process if it starts
becoming a problem.
---------
Co-authored-by: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com>
Part of #823
This PR adds a new HTTP header to the external link checker to set the
auth for GitHub when we are checking GitHub links. The new header is
only used for GitHub links following what we do in the closed-source
repo.
In order to be able to get the environment variable from typescript with
`process.env.GITHUB_TOKEN`, we need to define it in the workflows. In
the case of running the script locally, the token could be undefined.
---------
Co-authored-by: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com>
Closes#1330
This PR adds a check for the qiskit bot config to avoid the
`qiskit_bot.yaml` becoming stale.
The check shows two lists of files that can lead to an error:
The first one is for files that exist in the repo but don't have any
entry in the qiskit bot entry. This case will be triggered when we add
new files or we rename old ones without changing the configuration. If
we don't want to track a new file, we can add its path to the
`ALLOWED_OWNERLESS_FILES` set to avoid the error message.
The second list of files are the ones that don't exist in the repo but
have an entry in the config file. This case will be triggered by files
that change their name, removed files with the entry as a leftover, or
files where we set the config beforehand. The last ones can be added to
the `ALLOWED_INEXISTENT_FILES` set to avoid the error message.
The renamed files trigger both errors and will show the old name in the
first list, and the new name in the second one. This could be useful to
identify the old entries in the config file and to associate the files
in case we have multiple errors.
---------
Co-authored-by: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com>
Closes#547. This PR makes a new issue whenever the weekly checks fail.
We decided to create a new issue rather than reopening / commenting.
This reduces code complexity and lets us reuse the code from
`.github/workflows/learning-uploader-test.yml`.
I thought I'd tested this in #1154 but I actually only tested the
uploader test workflow. I'd forgotten to pass the environment from the
input to the job.
Something which wasn't my fault is that some tutorial UUIDs seem to have
changed, I'm not sure why this is but am investigating.
With the new UUIDs, the workflow is working ([see
run](https://github.com/Qiskit/documentation/actions/runs/8798350887/job/24145159885)).
Fixes https://github.com/Qiskit/documentation/pull/1207. We use
`list[str]` in type hints rather than `List[str]`, which was only added
in Python 3.9. So it broke CI.
Python 3.9 is fine as a floor, given that Python 3.12 is newest.
We currently test everything with Python 3.11, but this is a problem as
not all writers have it available on their system. We also want to make
sure our docs work with as many versions of Python as possible.
This PR allows writers to test their docs with any version of Python,
and sets CI to test with Python 3.8 (the minimum version that Qiskit
supports).
Adds a workflow to deploy tutorials from `main`, and documentation on
how to do it. This PR also switches to using environment secrets rather
than actions secrets, which should be more secure as we can limit who
can run them and which branches they can run on. See
https://github.com/Qiskit/documentation/actions/runs/8647825547/job/23710189504
for an example of the action using the staging environment.
---------
Co-authored-by: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com>
Adds the new tutorial notebooks to the same tests as the documentation
notebooks. Most tutorials run jobs on IBM Quantum so will only be tested
fortnightly in the cron job workflow.
Part of #1136
We run notebooks that submit jobs twice a month to check they don't
raise errors, but we currently throw away the results. This PR uploads
the executed notebooks as an artifact so we can inspect the outputs and
update the files in this repo with more recent output.
See https://github.com/Qiskit/documentation/actions/runs/8645293171 for
an example of this working.
---------
Co-authored-by: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com>
Closes#105
This is currently a draft of the new page. I'll keep making edits and
leave the PR here for folks to add their own comments/suggestions.
---------
Co-authored-by: ABBY CROSS <across@us.ibm.com>
Frank Harkins