scnc
/
qiskit-documentation
mirror of https://github.com/Qiskit/documentation.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
qiskit-documentation/package.json

69 lines
2.8 KiB
JSON
Raw Normal View History

Set up NPM, GitHub Actions, and cSpell (#52) 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>
2023-09-12 22:33:34 +08:00
{
"name": "docs",
"version": "0.1.0",
Update quantum-computing.ibm.com to quantum.ibm.com (#453) 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?
2023-12-03 07:18:40 +08:00
"description": "The documentation content home for https://docs.quantum.ibm.com.",
Set up NPM, GitHub Actions, and cSpell (#52) 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>
2023-09-12 22:33:34 +08:00
"author": "Qiskit Development Team",
"license": "Apache-2.0",
"scripts": {
Add patterns index validation (#1550) 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>
2024-06-19 21:02:45 +08:00
"check": "npm run check:qiskit-bot && npm run check:patterns-index && npm run check:metadata && npm run check:spelling && npm run check:internal-links && npm run check:orphan-pages && npm run check:fmt",
Add Jest and Sphinx parsing library (#61) ## Background First part of https://github.com/Qiskit/documentation/issues/9. The docs infrastructure expects MDX files, but `qiskit`, `qiskit-ibm-provider`, and `qiskit-ibm-runtime` use Sphinx to generate their API references from source code. So, @axelhzf created a pipeline to convert Sphinx output to MDX. We are moving that pipeline to live in open source since the API references are also open source. ## What this PR does This adds the `lib/sphinx` code and its tests. The code is copied over without change, other than adding copyright headers. The PR also sets up Jest. A follow up PR will add the actual parsing script. I split up the PRs since this adds non-trivial infrastructure like Jest, so to have a smaller PR to review. This code will be deleted from the internal repository once https://github.com/Qiskit/documentation/issues/9 is complete and the internal repository is consuming this one. ## Why Jest? We use Playwright in https://github.com/Qiskit/qiskit_sphinx_theme, so I considered using that too here for consistency. But I stuck with the internal repo's decision to use Jest because Playwright doesn't have an equivalent to `toMatchInlineSnapshot`. I think Playwright is awesome, but we're never going to have Playwright integration tests in this repository since we're not testing the docs site itself in this repo, i.e. we don't need to spin up a server. Jest is simpler for our unit tests. Co-authored-by: Axel Hernández Ferrera <axelhzf@gmail.com>
2023-09-29 21:33:32 +08:00
"check:metadata": "node -r esbuild-register scripts/commands/checkMetadata.ts",
Reconfigure cspell to use dictionaries (#873) Closes #827
2024-02-24 00:02:11 +08:00
"check:spelling": "cspell --relative --no-progress docs/**/*.md* docs/api/**/*.md* --config cspell/cSpell.json",
Autoformat TypeScript with Prettier (#76) 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.
2023-10-20 23:35:35 +08:00
"check:fmt": "prettier --check .",
Split internal and external link checker into separate programs (#916) 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.
2024-02-29 03:57:29 +08:00
"check:internal-links": "node -r esbuild-register scripts/commands/checkInternalLinks.ts",
"check:external-links": "node -r esbuild-register scripts/commands/checkExternalLinks.ts",
"check:pages-render": "node -r esbuild-register scripts/commands/checkPagesRender.ts",
Add patterns index validation (#1550) 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>
2024-06-19 21:02:45 +08:00
"check:patterns-index": "node -r esbuild-register scripts/commands/checkPatternsIndex.ts",
Check for orphan pages (#951) 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>
2024-03-09 01:32:34 +08:00
"check:orphan-pages": "node -r esbuild-register scripts/commands/checkOrphanPages.ts",
Add check for files in `qiskit_bot.yaml` (#1375) 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>
2024-05-16 00:13:30 +08:00
"check:qiskit-bot": "node -r esbuild-register scripts/commands/checkQiskitBotFiles.ts",
add script to remove stale images (#1016) Fixes #194
2024-03-12 22:13:54 +08:00
"check:stale-images": "node -r esbuild-register scripts/commands/checkStaleImages.ts",
Autoformat TypeScript with Prettier (#76) 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.
2023-10-20 23:35:35 +08:00
"fmt": "prettier --write .",
Add Jest and Sphinx parsing library (#61) ## Background First part of https://github.com/Qiskit/documentation/issues/9. The docs infrastructure expects MDX files, but `qiskit`, `qiskit-ibm-provider`, and `qiskit-ibm-runtime` use Sphinx to generate their API references from source code. So, @axelhzf created a pipeline to convert Sphinx output to MDX. We are moving that pipeline to live in open source since the API references are also open source. ## What this PR does This adds the `lib/sphinx` code and its tests. The code is copied over without change, other than adding copyright headers. The PR also sets up Jest. A follow up PR will add the actual parsing script. I split up the PRs since this adds non-trivial infrastructure like Jest, so to have a smaller PR to review. This code will be deleted from the internal repository once https://github.com/Qiskit/documentation/issues/9 is complete and the internal repository is consuming this one. ## Why Jest? We use Playwright in https://github.com/Qiskit/qiskit_sphinx_theme, so I considered using that too here for consistency. But I stuck with the internal repo's decision to use Jest because Playwright doesn't have an equivalent to `toMatchInlineSnapshot`. I think Playwright is awesome, but we're never going to have Playwright integration tests in this repository since we're not testing the docs site itself in this repo, i.e. we don't need to spin up a server. Jest is simpler for our unit tests. Co-authored-by: Axel Hernández Ferrera <axelhzf@gmail.com>
2023-09-29 21:33:32 +08:00
"test": "jest",
API generation script requires passing the version (#321) 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.
2023-11-10 12:48:05 +08:00
"typecheck": "tsc",
Automate the regeneration of the API docs (#739) ### 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>
2024-02-02 21:19:20 +08:00
"regen-apis": "node -r esbuild-register scripts/commands/regenerateApiDocs.ts",
Converting current API to historical (#405) 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
2023-11-29 01:25:09 +08:00
"gen-api": "node -r esbuild-register scripts/commands/updateApiDocs.ts",
"make-historical": "node -r esbuild-register scripts/commands/convertApiDocsToHistorical.ts"
Set up NPM, GitHub Actions, and cSpell (#52) 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>
2023-09-12 22:33:34 +08:00
},
"devDependencies": {
Add Jest and Sphinx parsing library (#61) ## Background First part of https://github.com/Qiskit/documentation/issues/9. The docs infrastructure expects MDX files, but `qiskit`, `qiskit-ibm-provider`, and `qiskit-ibm-runtime` use Sphinx to generate their API references from source code. So, @axelhzf created a pipeline to convert Sphinx output to MDX. We are moving that pipeline to live in open source since the API references are also open source. ## What this PR does This adds the `lib/sphinx` code and its tests. The code is copied over without change, other than adding copyright headers. The PR also sets up Jest. A follow up PR will add the actual parsing script. I split up the PRs since this adds non-trivial infrastructure like Jest, so to have a smaller PR to review. This code will be deleted from the internal repository once https://github.com/Qiskit/documentation/issues/9 is complete and the internal repository is consuming this one. ## Why Jest? We use Playwright in https://github.com/Qiskit/qiskit_sphinx_theme, so I considered using that too here for consistency. But I stuck with the internal repo's decision to use Jest because Playwright doesn't have an equivalent to `toMatchInlineSnapshot`. I think Playwright is awesome, but we're never going to have Playwright integration tests in this repository since we're not testing the docs site itself in this repo, i.e. we don't need to spin up a server. Jest is simpler for our unit tests. Co-authored-by: Axel Hernández Ferrera <axelhzf@gmail.com>
2023-09-29 21:33:32 +08:00
"@swc/jest": "^0.2.29",
Link checker: did you mean feature (#348) ### Summary This PR adds a suggestion of a valid link for every broken link that the link checker finds. This feature only works with internal links and anchors. To calculate the best replacement for a broken link, the function `didYouMean` in `scripts/lib/LinkChecker.ts` uses the [Levenshtein distance](https://en.wikipedia.org/wiki/Levenshtein_distance) between the broken link and all the files we have in docs, as it was originally suggested in #4. The package used to implement the Levenshtein distance calculation is [fast-levenshtein](https://www.npmjs.com/package/fast-levenshtein).
2023-11-17 01:10:19 +08:00
"@types/fast-levenshtein": "^0.0.4",
Add Jest and Sphinx parsing library (#61) ## Background First part of https://github.com/Qiskit/documentation/issues/9. The docs infrastructure expects MDX files, but `qiskit`, `qiskit-ibm-provider`, and `qiskit-ibm-runtime` use Sphinx to generate their API references from source code. So, @axelhzf created a pipeline to convert Sphinx output to MDX. We are moving that pipeline to live in open source since the API references are also open source. ## What this PR does This adds the `lib/sphinx` code and its tests. The code is copied over without change, other than adding copyright headers. The PR also sets up Jest. A follow up PR will add the actual parsing script. I split up the PRs since this adds non-trivial infrastructure like Jest, so to have a smaller PR to review. This code will be deleted from the internal repository once https://github.com/Qiskit/documentation/issues/9 is complete and the internal repository is consuming this one. ## Why Jest? We use Playwright in https://github.com/Qiskit/qiskit_sphinx_theme, so I considered using that too here for consistency. But I stuck with the internal repo's decision to use Jest because Playwright doesn't have an equivalent to `toMatchInlineSnapshot`. I think Playwright is awesome, but we're never going to have Playwright integration tests in this repository since we're not testing the docs site itself in this repo, i.e. we don't need to spin up a server. Jest is simpler for our unit tests. Co-authored-by: Axel Hernández Ferrera <axelhzf@gmail.com>
2023-09-29 21:33:32 +08:00
"@types/jest": "^29.5.5",
Add check for files in `qiskit_bot.yaml` (#1375) 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>
2024-05-16 00:13:30 +08:00
"@types/js-yaml": "^4.0.9",
Add Jest and Sphinx parsing library (#61) ## Background First part of https://github.com/Qiskit/documentation/issues/9. The docs infrastructure expects MDX files, but `qiskit`, `qiskit-ibm-provider`, and `qiskit-ibm-runtime` use Sphinx to generate their API references from source code. So, @axelhzf created a pipeline to convert Sphinx output to MDX. We are moving that pipeline to live in open source since the API references are also open source. ## What this PR does This adds the `lib/sphinx` code and its tests. The code is copied over without change, other than adding copyright headers. The PR also sets up Jest. A follow up PR will add the actual parsing script. I split up the PRs since this adds non-trivial infrastructure like Jest, so to have a smaller PR to review. This code will be deleted from the internal repository once https://github.com/Qiskit/documentation/issues/9 is complete and the internal repository is consuming this one. ## Why Jest? We use Playwright in https://github.com/Qiskit/qiskit_sphinx_theme, so I considered using that too here for consistency. But I stuck with the internal repo's decision to use Jest because Playwright doesn't have an equivalent to `toMatchInlineSnapshot`. I think Playwright is awesome, but we're never going to have Playwright integration tests in this repository since we're not testing the docs site itself in this repo, i.e. we don't need to spin up a server. Jest is simpler for our unit tests. Co-authored-by: Axel Hernández Ferrera <axelhzf@gmail.com>
2023-09-29 21:33:32 +08:00
"@types/lodash": "^4.14.198",
Check for valid metadata (#56) 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>
2023-09-19 22:01:28 +08:00
"@types/node": "^20.6.2",
Allow generating API docs for specific projects (#196) One of the ideas from https://github.com/Qiskit/documentation/issues/63. This is useful to me right now because I want to only redo qiskit-ibm-provider. `yargs` is a popular command line library in JavaScript. I've used it in a personal project and had a great experience with it. There will be future config we need to add, like probably having users tell us what CI URL to look at when generating the docs, whereas right now we pull from the live websites (see #63). I think it's likely that config will be best set via a config file, rather than command line arguments. But, even if we have that config file in the future, I still think we'd want `--packages` to be a CLI arg since that is a quick thing that you want to be flexible with setting, vs updating a file. If we switch 100% to a file, that's fine; we can always remove `yargs`.
2023-10-19 21:15:33 +08:00
"@types/yargs": "^17.0.28",
Add Jest and Sphinx parsing library (#61) ## Background First part of https://github.com/Qiskit/documentation/issues/9. The docs infrastructure expects MDX files, but `qiskit`, `qiskit-ibm-provider`, and `qiskit-ibm-runtime` use Sphinx to generate their API references from source code. So, @axelhzf created a pipeline to convert Sphinx output to MDX. We are moving that pipeline to live in open source since the API references are also open source. ## What this PR does This adds the `lib/sphinx` code and its tests. The code is copied over without change, other than adding copyright headers. The PR also sets up Jest. A follow up PR will add the actual parsing script. I split up the PRs since this adds non-trivial infrastructure like Jest, so to have a smaller PR to review. This code will be deleted from the internal repository once https://github.com/Qiskit/documentation/issues/9 is complete and the internal repository is consuming this one. ## Why Jest? We use Playwright in https://github.com/Qiskit/qiskit_sphinx_theme, so I considered using that too here for consistency. But I stuck with the internal repo's decision to use Jest because Playwright doesn't have an equivalent to `toMatchInlineSnapshot`. I think Playwright is awesome, but we're never going to have Playwright integration tests in this repository since we're not testing the docs site itself in this repo, i.e. we don't need to spin up a server. Jest is simpler for our unit tests. Co-authored-by: Axel Hernández Ferrera <axelhzf@gmail.com>
2023-09-29 21:33:32 +08:00
"cheerio": "^1.0.0-rc.12",
Check for valid metadata (#56) 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>
2023-09-19 22:01:28 +08:00
"cspell": "^7.3.2",
"esbuild-register": "^3.5.0",
Add Jest and Sphinx parsing library (#61) ## Background First part of https://github.com/Qiskit/documentation/issues/9. The docs infrastructure expects MDX files, but `qiskit`, `qiskit-ibm-provider`, and `qiskit-ibm-runtime` use Sphinx to generate their API references from source code. So, @axelhzf created a pipeline to convert Sphinx output to MDX. We are moving that pipeline to live in open source since the API references are also open source. ## What this PR does This adds the `lib/sphinx` code and its tests. The code is copied over without change, other than adding copyright headers. The PR also sets up Jest. A follow up PR will add the actual parsing script. I split up the PRs since this adds non-trivial infrastructure like Jest, so to have a smaller PR to review. This code will be deleted from the internal repository once https://github.com/Qiskit/documentation/issues/9 is complete and the internal repository is consuming this one. ## Why Jest? We use Playwright in https://github.com/Qiskit/qiskit_sphinx_theme, so I considered using that too here for consistency. But I stuck with the internal repo's decision to use Jest because Playwright doesn't have an equivalent to `toMatchInlineSnapshot`. I think Playwright is awesome, but we're never going to have Playwright integration tests in this repository since we're not testing the docs site itself in this repo, i.e. we don't need to spin up a server. Jest is simpler for our unit tests. Co-authored-by: Axel Hernández Ferrera <axelhzf@gmail.com>
2023-09-29 21:33:32 +08:00
"github-slugger": "^2.0.0",
Check for valid metadata (#56) 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>
2023-09-19 22:01:28 +08:00
"globby": "^13.2.2",
"gray-matter": "^4.0.3",
Add Jest and Sphinx parsing library (#61) ## Background First part of https://github.com/Qiskit/documentation/issues/9. The docs infrastructure expects MDX files, but `qiskit`, `qiskit-ibm-provider`, and `qiskit-ibm-runtime` use Sphinx to generate their API references from source code. So, @axelhzf created a pipeline to convert Sphinx output to MDX. We are moving that pipeline to live in open source since the API references are also open source. ## What this PR does This adds the `lib/sphinx` code and its tests. The code is copied over without change, other than adding copyright headers. The PR also sets up Jest. A follow up PR will add the actual parsing script. I split up the PRs since this adds non-trivial infrastructure like Jest, so to have a smaller PR to review. This code will be deleted from the internal repository once https://github.com/Qiskit/documentation/issues/9 is complete and the internal repository is consuming this one. ## Why Jest? We use Playwright in https://github.com/Qiskit/qiskit_sphinx_theme, so I considered using that too here for consistency. But I stuck with the internal repo's decision to use Jest because Playwright doesn't have an equivalent to `toMatchInlineSnapshot`. I think Playwright is awesome, but we're never going to have Playwright integration tests in this repository since we're not testing the docs site itself in this repo, i.e. we don't need to spin up a server. Jest is simpler for our unit tests. Co-authored-by: Axel Hernández Ferrera <axelhzf@gmail.com>
2023-09-29 21:33:32 +08:00
"hast-util-to-mdast": "^8.3.0",
"hast-util-to-text": "^3.1.0",
"is-absolute-url": "^4.0.1",
"jest": "^29.7.0",
"lodash": "^4.17.21",
"mdast": "^3.0.0",
Migrate API pipeline script from closed source (#64) Part 2 of https://github.com/Qiskit/documentation/issues/9. The final part will run this script to generate the API docs. There are some things I want to tweak in the script like that the qiskit-ibm-runtime site has changed URLs, but I wanted to avoid making changes to the script in this PR so that it simply copies them over. This PR simply copies over the API pipeline written by @axelhzf from closed source to open source. Its only modifications are adding copyright headers and removing unused code from utility files. https://github.com/Qiskit/documentation/issues/63 tracks some ideas to simplify this pipeline in follow ups, such as not needing GitHub. Co-authored-by: Axel Hernández Ferrera <axelhzf@gmail.com>
2023-09-29 22:55:52 +08:00
"mkdirp": "^3.0.1",
"p-map": "^6.0.0",
Autoformat TypeScript with Prettier (#76) 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.
2023-10-20 23:35:35 +08:00
"prettier": "^3.0.3",
Add Jest and Sphinx parsing library (#61) ## Background First part of https://github.com/Qiskit/documentation/issues/9. The docs infrastructure expects MDX files, but `qiskit`, `qiskit-ibm-provider`, and `qiskit-ibm-runtime` use Sphinx to generate their API references from source code. So, @axelhzf created a pipeline to convert Sphinx output to MDX. We are moving that pipeline to live in open source since the API references are also open source. ## What this PR does This adds the `lib/sphinx` code and its tests. The code is copied over without change, other than adding copyright headers. The PR also sets up Jest. A follow up PR will add the actual parsing script. I split up the PRs since this adds non-trivial infrastructure like Jest, so to have a smaller PR to review. This code will be deleted from the internal repository once https://github.com/Qiskit/documentation/issues/9 is complete and the internal repository is consuming this one. ## Why Jest? We use Playwright in https://github.com/Qiskit/qiskit_sphinx_theme, so I considered using that too here for consistency. But I stuck with the internal repo's decision to use Jest because Playwright doesn't have an equivalent to `toMatchInlineSnapshot`. I think Playwright is awesome, but we're never going to have Playwright integration tests in this repository since we're not testing the docs site itself in this repo, i.e. we don't need to spin up a server. Jest is simpler for our unit tests. Co-authored-by: Axel Hernández Ferrera <axelhzf@gmail.com>
2023-09-29 21:33:32 +08:00
"rehype-parse": "^8.0.0",
"rehype-remark": "^9.1.2",
"remark-gfm": "^3.0.1",
"remark-math": "^5.1.1",
"remark-mdx": "^2.3.0",
"remark-parse": "^10.0.1",
"remark-stringify": "^10.0.3",
"typescript": "^5.2.2",
"unified": "^10.0.0",
Migrate API pipeline script from closed source (#64) Part 2 of https://github.com/Qiskit/documentation/issues/9. The final part will run this script to generate the API docs. There are some things I want to tweak in the script like that the qiskit-ibm-runtime site has changed URLs, but I wanted to avoid making changes to the script in this PR so that it simply copies them over. This PR simply copies over the API pipeline written by @axelhzf from closed source to open source. Its only modifications are adding copyright headers and removing unused code from utility files. https://github.com/Qiskit/documentation/issues/63 tracks some ideas to simplify this pipeline in follow ups, such as not needing GitHub. Co-authored-by: Axel Hernández Ferrera <axelhzf@gmail.com>
2023-09-29 22:55:52 +08:00
"unist-util-visit": "^4.0.0",
Allow generating API docs for specific projects (#196) One of the ideas from https://github.com/Qiskit/documentation/issues/63. This is useful to me right now because I want to only redo qiskit-ibm-provider. `yargs` is a popular command line library in JavaScript. I've used it in a personal project and had a great experience with it. There will be future config we need to add, like probably having users tell us what CI URL to look at when generating the docs, whereas right now we pull from the live websites (see #63). I think it's likely that config will be best set via a config file, rather than command line arguments. But, even if we have that config file in the future, I still think we'd want `--packages` to be a CLI arg since that is a quick thing that you want to be flexible with setting, vs updating a file. If we switch 100% to a file, that's fine; we can always remove `yargs`.
2023-10-19 21:15:33 +08:00
"yargs": "^17.7.2",
Migrate API pipeline script from closed source (#64) Part 2 of https://github.com/Qiskit/documentation/issues/9. The final part will run this script to generate the API docs. There are some things I want to tweak in the script like that the qiskit-ibm-runtime site has changed URLs, but I wanted to avoid making changes to the script in this PR so that it simply copies them over. This PR simply copies over the API pipeline written by @axelhzf from closed source to open source. Its only modifications are adding copyright headers and removing unused code from utility files. https://github.com/Qiskit/documentation/issues/63 tracks some ideas to simplify this pipeline in follow ups, such as not needing GitHub. Co-authored-by: Axel Hernández Ferrera <axelhzf@gmail.com>
2023-09-29 22:55:52 +08:00
"zx": "^7.2.3"
Add script to check links (#173) This PR adds a link-checking script to verify internal links work. It should be easy to extend this to check external links, and anchors within internal links. All comments welcome. ### Details Uses `markdown-link-extractor`, which is used by `markdown-link-check` (one of the proposed tools). *** First part of #4
2023-10-19 22:23:47 +08:00
},
"dependencies": {
Add expanded alt text for relevant images (#627) Closes #626 --------- Co-authored-by: abbycross <across@us.ibm.com>
2024-01-24 05:21:36 +08:00
"esbuild": "^0.19.11",
Link checker: did you mean feature (#348) ### Summary This PR adds a suggestion of a valid link for every broken link that the link checker finds. This feature only works with internal links and anchors. To calculate the best replacement for a broken link, the function `didYouMean` in `scripts/lib/LinkChecker.ts` uses the [Levenshtein distance](https://en.wikipedia.org/wiki/Levenshtein_distance) between the broken link and all the files we have in docs, as it was originally suggested in #4. The package used to implement the Levenshtein distance calculation is [fast-levenshtein](https://www.npmjs.com/package/fast-levenshtein).
2023-11-17 01:10:19 +08:00
"fast-levenshtein": "^3.0.0",
Fix Qiskit release notes relative links (#400) This PR fixes the broken relative links of the Qiskit release notes. The links are originally valid, but because we have the release notes in a subfolder, we need to update the relative paths. To update every link, I used the `updateApiDocs.ts` script, but added another function to read every link and add `/api/qiskit` in front of each relative path. This function was executed in line 220, followed by process.exit() to avoid doing anything else. <details> <summary>Function to convert relative links</summary> ```typescript async function updateLinksReleaseNotes( projectName: string, legacyReleaseNoteEntries: { title: string; url: string }[], ) { for (let entry of legacyReleaseNoteEntries) { let source = await readFile( `${getRoot()}/docs/api/${projectName}/release-notes/${entry.title}.md`, { encoding: "utf8" }, ); source = transformLinks(source, (link, _) => link.startsWith("http") || link.startsWith("#") || link.startsWith("/") ? link : `/api/${projectName}/${link}`, ); await writeFile( `${getRoot()}/docs/api/${projectName}/release-notes/${entry.title}.md`, source, ); } } ``` </details> The PR still needs to modify the `updateApiDocs.ts` to update the relative links of the newest release notes we download when we run the script. Closes #386
2023-11-24 18:48:41 +08:00
"markdown-link-extractor": "^3.1.0",
"transform-markdown-links": "^2.1.0"
Set up NPM, GitHub Actions, and cSpell (#52) 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>
2023-09-12 22:33:34 +08:00
}
}