Skip to content

Commit dd9809b

Browse files
Eric-Arellanoaxelhzfeharvey328
authored
Set up NPM, GitHub Actions, and cSpell (Qiskit#52)
Closes Qiskit#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>
1 parent 7af8aac commit dd9809b

File tree

8 files changed

+2227
-1
lines changed

8 files changed

+2227
-1
lines changed

‎.github/workflows/main.yml

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
name: Lint
2+
on: [pull_request]
3+
jobs:
4+
lint:
5+
name: Lint
6+
runs-on: ubuntu-latest
7+
if: github.repository_owner == 'Qiskit'
8+
steps:
9+
- uses: actions/checkout@v4
10+
- name: Set up Node.js
11+
uses: actions/setup-node@v3
12+
with:
13+
node-version: 18
14+
- name: Install Node.js dependencies
15+
run: npm ci
16+
17+
- name: Spellcheck
18+
run: npm run spellcheck

‎.gitignore

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
.idea/
2+
.vscode/
3+
.fleet/
4+
5+
.DS_Store
6+
7+
node_modules

‎README.md

Lines changed: 51 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,51 @@
1-
# docs
1+
# Qiskit docs
2+
3+
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.
4+
5+
# How tos
6+
7+
## Pre-requisites to run tools locally
8+
9+
These tools will also run in CI. But, it can be convenient when iterating to run the tools locally.
10+
11+
First, install the below:
12+
13+
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).
14+
15+
Then, install the dependencies with:
16+
17+
```bash
18+
npm install
19+
```
20+
21+
## Spellcheck
22+
23+
We use [cSpell](https://cspell.org) to check for spelling. The `lint` job in CI will fail if there are spelling issues.
24+
25+
There are two ways to check spelling locally, rather than needing CI.
26+
27+
1.
28+
29+
```bash
30+
npm run spellcheck
31+
```
32+
33+
2. Use the VSCode extension [Code Spell Checker](https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker).
34+
35+
### Fixing false positives
36+
37+
There are two ways to deal with cSpell incorrectly complaining about a word, such as abbreviations.
38+
39+
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.
40+
41+
```
42+
{/* cspell:ignore hellllooooo, ayyyyy */}
43+
44+
# Hellllooooo!
45+
46+
Ayyyyy, this is a fake description.
47+
```
48+
49+
2. Add the word to the file `cSpell.json` in the `words` section. The word is not case-sensitive.
50+
51+
If the word appears in multiple files, prefer the second approach to add it to `cSpell.json`.

‎cSpell.json

Lines changed: 263 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,263 @@
1+
// This file is copied from IBM's closed source configuration. When updating it
2+
// here, also update the closed source repository, or ask a maintainer to do so
3+
// if you do not have access.
4+
{
5+
"version": "0.2",
6+
"language": "en",
7+
"allowCompoundWords": true,
8+
"words": [
9+
"Aaronson",
10+
"Ahokas",
11+
"Abelian",
12+
"Abhari",
13+
"Almaden",
14+
"Alon",
15+
"Ambainis",
16+
"Ansatz",
17+
"anticommute",
18+
"anticommutes",
19+
"arccos",
20+
"arcsin",
21+
"arctan",
22+
"argsort",
23+
"arity",
24+
"autodifferentiation",
25+
"ancillae",
26+
"ancillas",
27+
"ansatzes",
28+
"bijective",
29+
"Boeblingen",
30+
"Bravyi",
31+
"Bremner",
32+
"Bruhat",
33+
"Bures",
34+
"Canonicalization",
35+
"Capelluto",
36+
"Chebyshev",
37+
"Choi",
38+
"Chong",
39+
"Chuang",
40+
"qubit",
41+
"qubits",
42+
"Qiskit",
43+
"qasm",
44+
"Hamiltonians",
45+
"Eigensolver",
46+
"exponentials",
47+
"Hadamard",
48+
"matplotlib",
49+
"numpy",
50+
"Kraus",
51+
"unitaries",
52+
"decomp",
53+
"Paulis",
54+
"Cleve",
55+
"Trotterization",
56+
"Solovay",
57+
"Kitaev",
58+
"Cliffords",
59+
"connectivities",
60+
"Cuccaro",
61+
"destabilizer",
62+
"detuning",
63+
"Dueck",
64+
"Easwar",
65+
"eigenstate",
66+
"eigenstates",
67+
"Eisert",
68+
"equispaced",
69+
"fermionic",
70+
"Frobenius",
71+
"Gosset",
72+
"Gottesman",
73+
"Gushu",
74+
"Häner",
75+
"Hardamard",
76+
"Havlicek",
77+
"Hein",
78+
"Hiptmair",
79+
"Hoare",
80+
"Hoyer",
81+
"initialised",
82+
"initialiser",
83+
"ints",
84+
"Ipython",
85+
"ipywidgets",
86+
"Iten",
87+
"Itoko",
88+
"Javadi",
89+
"Jurcevic",
90+
"Ketan",
91+
"Koenig",
92+
"Kolkata",
93+
"Kutin",
94+
"Lauer",
95+
"Margolus",
96+
"Martonosi",
97+
"Maslov",
98+
"Merkel",
99+
"Mølmer",
100+
"Moscas",
101+
"Motzoi",
102+
"Moyard",
103+
"multinomial",
104+
"multiqubit",
105+
"Murali",
106+
"Nannicini",
107+
"Nesterov’s",
108+
"Neumann",
109+
"openqasm",
110+
"Ourense",
111+
"parameterizing",
112+
"Paulihedral",
113+
"polynomially",
114+
"Poppler",
115+
"Prakash",
116+
"pygments",
117+
"pyplot",
118+
"Raban",
119+
"Rebentrost",
120+
"Renato",
121+
"Renner",
122+
"rescheduler",
123+
"resynthesized",
124+
"Roetteler",
125+
"Rueschlikon",
126+
"schedulable",
127+
"Shaohan",
128+
"Shaydulin",
129+
"Shende",
130+
"Shor’s",
131+
"Simonetto",
132+
"Smolin",
133+
"Sørensen",
134+
"struct",
135+
"structs",
136+
"Sutter",
137+
"Svore",
138+
"Symegine",
139+
"symplectic",
140+
"tensored",
141+
"Theor",
142+
"Toffoli",
143+
"uncompiled",
144+
"uncompute",
145+
"uncomputed",
146+
"unentanglement",
147+
"unnormalized",
148+
"Unroller",
149+
"Vazirani",
150+
"Vedral",
151+
"Watrous",
152+
"Weyl",
153+
"Woerner",
154+
"Yufei",
155+
"Zoufal",
156+
"Mosca",
157+
"pydot",
158+
"qudit",
159+
"qutrit",
160+
"Uhrig",
161+
"saveas",
162+
"Tapp",
163+
"extremal",
164+
"Anharmonicity",
165+
"ALAP",
166+
"atol",
167+
"ASPLOS",
168+
"BFGS",
169+
"CDKM",
170+
"CNOT",
171+
"stddev",
172+
"expval",
173+
"qsphere",
174+
"cargs",
175+
"cbit",
176+
"cbits",
177+
"opflow",
178+
"qobj",
179+
"ibmq",
180+
"clbit",
181+
"Clbits",
182+
"cmap",
183+
"cnots",
184+
"coeff",
185+
"coeffs",
186+
"CPLEX",
187+
"CPTP",
188+
"creg",
189+
"cregs",
190+
"csdg",
191+
"CSWAP",
192+
"CVXPY",
193+
"DIMACS",
194+
"docplex",
195+
"dtype",
196+
"Fieldr",
197+
"fsim",
198+
"kwarg",
199+
"kwargs",
200+
"kwparams",
201+
"lnot",
202+
"mathbb",
203+
"nqubits",
204+
"paulivec",
205+
"qarg",
206+
"qargs",
207+
"qreg",
208+
"qregs",
209+
"regs",
210+
"xgate",
211+
"basicaer",
212+
"basicaererror",
213+
"cregbundle",
214+
"iqft",
215+
"iswap",
216+
"MCMT",
217+
"MCMTV",
218+
"ndarray",
219+
"NISQ",
220+
"nxpd",
221+
"oper",
222+
"PRNG",
223+
"QAOA",
224+
"rcccx",
225+
"RCCX",
226+
"repr",
227+
"rtol",
228+
"rustworkx",
229+
"sched",
230+
"sxdg",
231+
"srepr",
232+
"sympy",
233+
"TOQM",
234+
"uchannel",
235+
"UCRX",
236+
"UCRY",
237+
"UCRZ",
238+
"XIYY",
239+
"ZSXX",
240+
"qelib",
241+
"QVSM"
242+
],
243+
"ignoreRegExpList": [
244+
// Markdown links
245+
"\\((.*)\\)",
246+
// markdown code blocks. https://github.com/streetsidesoftware/vscode-spell-checker/issues/202#issuecomment-377477473
247+
"/^\\s*```[\\s\\S]*?^\\s*```/gm",
248+
// inline code blocks. https://stackoverflow.com/questions/41274241/how-to-capture-inline-markdown-code-but-not-a-markdown-code-fence-with-regex
249+
"\\`([^\\`].*?)\\`",
250+
// $$ ... $$ code blocks
251+
"\\$\\$\n(?:.*\n)*?\\$\\$",
252+
// markdown metadata block. e.g. title, description, etc.
253+
"---\n(?:.*\n)*?---",
254+
// words inside curly braces. e.g. {word}
255+
"{\\w+}",
256+
// words inside colons. e.g. :word:
257+
":\\S+:",
258+
// words joined by underscores. e.g. hello_world, NEW_KEY_VALUE
259+
"\\S+_\\S+(_\\S+)*",
260+
// separate line <span id="" /> tags
261+
"^<span id=\\S+ />$"
262+
]
263+
}

‎docs/placeholder.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Placeholder
2+
3+
Until we migrate docs, this is only to set up the repository structure.

0 commit comments

Comments
 (0)