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>
This commit is contained in:
Eric Arellano
GitHub
parent
7af8aac133
commit
dd9809bd5c
|
|
@ -0,0 +1,18 @@
|
|||
name: Lint
|
||||
on: [pull_request]
|
||||
jobs:
|
||||
lint:
|
||||
name: Lint
|
||||
runs-on: ubuntu-latest
|
||||
if: github.repository_owner == 'Qiskit'
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- name: Set up Node.js
|
||||
uses: actions/setup-node@v3
|
||||
with:
|
||||
node-version: 18
|
||||
- name: Install Node.js dependencies
|
||||
run: npm ci
|
||||
|
||||
- name: Spellcheck
|
||||
run: npm run spellcheck
|
||||
|
|
@ -0,0 +1,7 @@
|
|||
.idea/
|
||||
.vscode/
|
||||
.fleet/
|
||||
|
||||
.DS_Store
|
||||
|
||||
node_modules
|
||||
52
README.md
52
README.md
|
|
@ -1 +1,51 @@
|
|||
# docs
|
||||
# Qiskit docs
|
||||
|
||||
The documentation content home for https://docs.quantum-computing.ibm.com. Refer to https://github.com/Qiskit/qiskit to make changes to the docs at https://qiskit.org/documentation.
|
||||
|
||||
# How tos
|
||||
|
||||
## Pre-requisites to run tools locally
|
||||
|
||||
These tools will also run in CI. But, it can be convenient when iterating to run the tools locally.
|
||||
|
||||
First, install the below:
|
||||
|
||||
1. [Node.js](https://nodejs.org/en). If you expect to use JavaScript in other projects, consider using [NVM](https://github.com/nvm-sh/nvm). Otherwise, consider using [Homebrew](https://formulae.brew.sh/formula/node) or installing [Node.js directly](https://nodejs.org/en).
|
||||
|
||||
Then, install the dependencies with:
|
||||
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
|
||||
## Spellcheck
|
||||
|
||||
We use [cSpell](https://cspell.org) to check for spelling. The `lint` job in CI will fail if there are spelling issues.
|
||||
|
||||
There are two ways to check spelling locally, rather than needing CI.
|
||||
|
||||
1.
|
||||
|
||||
```bash
|
||||
npm run spellcheck
|
||||
```
|
||||
|
||||
2. Use the VSCode extension [Code Spell Checker](https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker).
|
||||
|
||||
### Fixing false positives
|
||||
|
||||
There are two ways to deal with cSpell incorrectly complaining about a word, such as abbreviations.
|
||||
|
||||
1. Ignore the word in the local markdown file by adding a comment to the file, like below. The word is not case-sensitive, and the comment can be placed anywhere.
|
||||
|
||||
```
|
||||
{/* cspell:ignore hellllooooo, ayyyyy */}
|
||||
|
||||
# Hellllooooo!
|
||||
|
||||
Ayyyyy, this is a fake description.
|
||||
```
|
||||
|
||||
2. Add the word to the file `cSpell.json` in the `words` section. The word is not case-sensitive.
|
||||
|
||||
If the word appears in multiple files, prefer the second approach to add it to `cSpell.json`.
|
||||
|
|
|
|||
|
|
@ -0,0 +1,263 @@
|
|||
// This file is copied from IBM's closed source configuration. When updating it
|
||||
// here, also update the closed source repository, or ask a maintainer to do so
|
||||
// if you do not have access.
|
||||
{
|
||||
"version": "0.2",
|
||||
"language": "en",
|
||||
"allowCompoundWords": true,
|
||||
"words": [
|
||||
"Aaronson",
|
||||
"Ahokas",
|
||||
"Abelian",
|
||||
"Abhari",
|
||||
"Almaden",
|
||||
"Alon",
|
||||
"Ambainis",
|
||||
"Ansatz",
|
||||
"anticommute",
|
||||
"anticommutes",
|
||||
"arccos",
|
||||
"arcsin",
|
||||
"arctan",
|
||||
"argsort",
|
||||
"arity",
|
||||
"autodifferentiation",
|
||||
"ancillae",
|
||||
"ancillas",
|
||||
"ansatzes",
|
||||
"bijective",
|
||||
"Boeblingen",
|
||||
"Bravyi",
|
||||
"Bremner",
|
||||
"Bruhat",
|
||||
"Bures",
|
||||
"Canonicalization",
|
||||
"Capelluto",
|
||||
"Chebyshev",
|
||||
"Choi",
|
||||
"Chong",
|
||||
"Chuang",
|
||||
"qubit",
|
||||
"qubits",
|
||||
"Qiskit",
|
||||
"qasm",
|
||||
"Hamiltonians",
|
||||
"Eigensolver",
|
||||
"exponentials",
|
||||
"Hadamard",
|
||||
"matplotlib",
|
||||
"numpy",
|
||||
"Kraus",
|
||||
"unitaries",
|
||||
"decomp",
|
||||
"Paulis",
|
||||
"Cleve",
|
||||
"Trotterization",
|
||||
"Solovay",
|
||||
"Kitaev",
|
||||
"Cliffords",
|
||||
"connectivities",
|
||||
"Cuccaro",
|
||||
"destabilizer",
|
||||
"detuning",
|
||||
"Dueck",
|
||||
"Easwar",
|
||||
"eigenstate",
|
||||
"eigenstates",
|
||||
"Eisert",
|
||||
"equispaced",
|
||||
"fermionic",
|
||||
"Frobenius",
|
||||
"Gosset",
|
||||
"Gottesman",
|
||||
"Gushu",
|
||||
"Häner",
|
||||
"Hardamard",
|
||||
"Havlicek",
|
||||
"Hein",
|
||||
"Hiptmair",
|
||||
"Hoare",
|
||||
"Hoyer",
|
||||
"initialised",
|
||||
"initialiser",
|
||||
"ints",
|
||||
"Ipython",
|
||||
"ipywidgets",
|
||||
"Iten",
|
||||
"Itoko",
|
||||
"Javadi",
|
||||
"Jurcevic",
|
||||
"Ketan",
|
||||
"Koenig",
|
||||
"Kolkata",
|
||||
"Kutin",
|
||||
"Lauer",
|
||||
"Margolus",
|
||||
"Martonosi",
|
||||
"Maslov",
|
||||
"Merkel",
|
||||
"Mølmer",
|
||||
"Moscas",
|
||||
"Motzoi",
|
||||
"Moyard",
|
||||
"multinomial",
|
||||
"multiqubit",
|
||||
"Murali",
|
||||
"Nannicini",
|
||||
"Nesterov’s",
|
||||
"Neumann",
|
||||
"openqasm",
|
||||
"Ourense",
|
||||
"parameterizing",
|
||||
"Paulihedral",
|
||||
"polynomially",
|
||||
"Poppler",
|
||||
"Prakash",
|
||||
"pygments",
|
||||
"pyplot",
|
||||
"Raban",
|
||||
"Rebentrost",
|
||||
"Renato",
|
||||
"Renner",
|
||||
"rescheduler",
|
||||
"resynthesized",
|
||||
"Roetteler",
|
||||
"Rueschlikon",
|
||||
"schedulable",
|
||||
"Shaohan",
|
||||
"Shaydulin",
|
||||
"Shende",
|
||||
"Shor’s",
|
||||
"Simonetto",
|
||||
"Smolin",
|
||||
"Sørensen",
|
||||
"struct",
|
||||
"structs",
|
||||
"Sutter",
|
||||
"Svore",
|
||||
"Symegine",
|
||||
"symplectic",
|
||||
"tensored",
|
||||
"Theor",
|
||||
"Toffoli",
|
||||
"uncompiled",
|
||||
"uncompute",
|
||||
"uncomputed",
|
||||
"unentanglement",
|
||||
"unnormalized",
|
||||
"Unroller",
|
||||
"Vazirani",
|
||||
"Vedral",
|
||||
"Watrous",
|
||||
"Weyl",
|
||||
"Woerner",
|
||||
"Yufei",
|
||||
"Zoufal",
|
||||
"Mosca",
|
||||
"pydot",
|
||||
"qudit",
|
||||
"qutrit",
|
||||
"Uhrig",
|
||||
"saveas",
|
||||
"Tapp",
|
||||
"extremal",
|
||||
"Anharmonicity",
|
||||
"ALAP",
|
||||
"atol",
|
||||
"ASPLOS",
|
||||
"BFGS",
|
||||
"CDKM",
|
||||
"CNOT",
|
||||
"stddev",
|
||||
"expval",
|
||||
"qsphere",
|
||||
"cargs",
|
||||
"cbit",
|
||||
"cbits",
|
||||
"opflow",
|
||||
"qobj",
|
||||
"ibmq",
|
||||
"clbit",
|
||||
"Clbits",
|
||||
"cmap",
|
||||
"cnots",
|
||||
"coeff",
|
||||
"coeffs",
|
||||
"CPLEX",
|
||||
"CPTP",
|
||||
"creg",
|
||||
"cregs",
|
||||
"csdg",
|
||||
"CSWAP",
|
||||
"CVXPY",
|
||||
"DIMACS",
|
||||
"docplex",
|
||||
"dtype",
|
||||
"Fieldr",
|
||||
"fsim",
|
||||
"kwarg",
|
||||
"kwargs",
|
||||
"kwparams",
|
||||
"lnot",
|
||||
"mathbb",
|
||||
"nqubits",
|
||||
"paulivec",
|
||||
"qarg",
|
||||
"qargs",
|
||||
"qreg",
|
||||
"qregs",
|
||||
"regs",
|
||||
"xgate",
|
||||
"basicaer",
|
||||
"basicaererror",
|
||||
"cregbundle",
|
||||
"iqft",
|
||||
"iswap",
|
||||
"MCMT",
|
||||
"MCMTV",
|
||||
"ndarray",
|
||||
"NISQ",
|
||||
"nxpd",
|
||||
"oper",
|
||||
"PRNG",
|
||||
"QAOA",
|
||||
"rcccx",
|
||||
"RCCX",
|
||||
"repr",
|
||||
"rtol",
|
||||
"rustworkx",
|
||||
"sched",
|
||||
"sxdg",
|
||||
"srepr",
|
||||
"sympy",
|
||||
"TOQM",
|
||||
"uchannel",
|
||||
"UCRX",
|
||||
"UCRY",
|
||||
"UCRZ",
|
||||
"XIYY",
|
||||
"ZSXX",
|
||||
"qelib",
|
||||
"QVSM"
|
||||
],
|
||||
"ignoreRegExpList": [
|
||||
// Markdown links
|
||||
"\\((.*)\\)",
|
||||
// markdown code blocks. https://github.com/streetsidesoftware/vscode-spell-checker/issues/202#issuecomment-377477473
|
||||
"/^\\s*```[\\s\\S]*?^\\s*```/gm",
|
||||
// inline code blocks. https://stackoverflow.com/questions/41274241/how-to-capture-inline-markdown-code-but-not-a-markdown-code-fence-with-regex
|
||||
"\\`([^\\`].*?)\\`",
|
||||
// $$ ... $$ code blocks
|
||||
"\\$\\$\n(?:.*\n)*?\\$\\$",
|
||||
// markdown metadata block. e.g. title, description, etc.
|
||||
"---\n(?:.*\n)*?---",
|
||||
// words inside curly braces. e.g. {word}
|
||||
"{\\w+}",
|
||||
// words inside colons. e.g. :word:
|
||||
":\\S+:",
|
||||
// words joined by underscores. e.g. hello_world, NEW_KEY_VALUE
|
||||
"\\S+_\\S+(_\\S+)*",
|
||||
// separate line <span id="" /> tags
|
||||
"^<span id=\\S+ />$"
|
||||
]
|
||||
}
|
||||
|
|
@ -0,0 +1,3 @@
|
|||
# Placeholder
|
||||
|
||||
Until we migrate docs, this is only to set up the repository structure.
|
||||
File diff suppressed because it is too large
Load Diff
|
|
@ -0,0 +1,13 @@
|
|||
{
|
||||
"name": "docs",
|
||||
"version": "0.1.0",
|
||||
"description": "The documentation content home for https://docs.quantum-computing.ibm.com.",
|
||||
"author": "Qiskit Development Team",
|
||||
"license": "Apache-2.0",
|
||||
"scripts": {
|
||||
"spellcheck": "cspell --relative --no-progress docs/**/*.md*"
|
||||
},
|
||||
"devDependencies": {
|
||||
"cspell": "^7.3.2"
|
||||
}
|
||||
}
|
||||
|
|
@ -0,0 +1 @@
|
|||
Until we migrate docs, this is only to set up the repository structure.
|
||||
Loading…
Reference in New Issue