Add writing linting with Vale

CONTRIBUTING.md

@@ -270,6 +270,17 @@ out$> make style
 out$> make mypy
 ```
 
+If you edit any documentation, refer to [IBM Quantum's writing style
+guide](https://github.com/IBM/ibm-quantum-style-guide). You can use
+[Vale](https://vale.sh) to automatically check some of these rules for you.
+With Vale installed, run the following command
+
+```sh
+make docs-test
+```
+
+To add a word to the dictionary, add it to `test/docs/dictionary.txt`.
+
 ### Development Cycle
 
 The development cycle for qiskit-ibm  is all handled in the open using

Makefile

@@ -32,6 +32,9 @@ integration-test:
 e2e-test:
 	python -m unittest discover --verbose --top-level-directory . --start-directory test/e2e
 
+docs-test:
+	./test/docs/vale.sh
+
 unit-test-coverage:
 	coverage run -m unittest discover --verbose --top-level-directory . --start-directory test/unit
 	coverage lcov

docs/.vale.ini

@@ -0,0 +1,12 @@
+StylesPath = ../test/docs
+MinAlertLevel = suggestion
+
+[[!_]**.{md,rst}]
+BasedOnStyles = IBMQuantum
+
+[apidocs/ibm-runtime.rst]
+IBMQuantum.Headings = NO
+
+# skip './stubs'
+[stubs/**]
+BasedOnStyles = ''

requirements-dev.txt

@@ -7,6 +7,7 @@ sphinx-rtd-theme>=0.4.0
 sphinx-tabs>=1.1.11
 sphinx-automodapi
 sphinx-autodoc-typehints<=1.19.2
+nbqa==1.5.3
 matplotlib>=2.1
 jupyter
 jupyter-sphinx

test/docs/IBMQuantum/Abbreviations.yml

@@ -0,0 +1,7 @@
+extends: existence
+message: "Do not use periods in all-uppercase abbreviations such as '%s'."
+link: 'https://www.ibm.com/developerworks/library/styleguidelines/index.html#N100DC'
+level: error
+nonword: true
+tokens:
+  - '\b(?:[A-Z]\.){3,5}'

test/docs/IBMQuantum/DashSpacing.yml

@@ -0,0 +1,13 @@
+extends: existence
+message: "Add spaces around the dash in '%s'."
+link: 'https://www.ibm.com/developerworks/library/styleguidelines/index.html#N106BF'
+ignorecase: true
+nonword: true
+level: error
+action:
+  name: edit
+  params:
+    - remove
+    - ' '
+tokens:
+  - '[^\s][—–][^\s]'

test/docs/IBMQuantum/Definitions.yml

@@ -0,0 +1,69 @@
+extends: conditional
+message: "Define acronyms and abbreviations (such as '%s') on first occurrence if they're likely to be unfamiliar."
+link: 'https://www.ibm.com/developerworks/library/styleguidelines/index.html#N100DC'
+level: suggestion
+ignorecase: false
+# Ensures that the existence of 'first' implies the existence of 'second'.
+first: '\b([A-Z]{3,5}s?)\b'
+second: '\(([A-Z]{3,5}s?)\)'
+# ... with the exception of these:
+exceptions:
+  - API
+  - ASP
+  - CLI
+  - CPU
+  - CNOT
+  - CSS
+  - CSV
+  - DEBUG
+  - DOM
+  - DPI
+  - FAQ
+  - GCC
+  - GDB
+  - GET
+  - GPU
+  - GTK
+  - GUI
+  - HTML
+  - HTTP
+  - HTTPS
+  - IBM
+  - IDE
+  - JAR
+  - JSON
+  - JSX
+  - LESS
+  - LLDB
+  - NBQA
+  - NET
+  - NOTE
+  - NVDA
+  - OSS
+  - PATH
+  - PDF
+  - PHP
+  - POST
+  - QPU
+  - RAM
+  - REPL
+  - RSA
+  - SCM
+  - SCSS
+  - SDK
+  - SQL
+  - SSH
+  - SSL
+  - SVG
+  - SWAT
+  - TBD
+  - TCP
+  - TODO
+  - URI
+  - URL
+  - USB
+  - UTF
+  - XML
+  - XSS
+  - YAML
+  - ZIP

test/docs/IBMQuantum/Headings.yml

@@ -0,0 +1,28 @@
+extends: capitalization
+message: "'%s' should use sentence-style capitalization."
+link: 'https://www.ibm.com/developerworks/library/styleguidelines/index.html#N1030C'
+level: warning
+scope: heading
+match: $sentence
+indicators:
+  - ':'
+  - '.'
+  - ')'
+exceptions:
+  - API
+  - App ID
+  - IBM
+  - IBM Quantum
+  - Qiskit
+  - Runtime
+  - Sampler
+  - Estimator
+  - Terraform
+  - Trotter
+  - Grover
+  - Hamiltonian
+  - Hamiltonians
+  - Cloud
+  - Spectroscopic Eigensolver Algorithm
+  - Variational Quantum Eigensolver
+  - (\d+)\. 

test/docs/IBMQuantum/However.yml

@@ -0,0 +1,7 @@
+extends: existence
+message: Double-check your punctuation around 'however' (see github.com/IBM/ibm-quantum-style-guide/issues/10 for more information).
+level: suggestion
+code: false
+ignorecase: false
+raw:
+    - ([^;,] however|however[^,])

test/docs/IBMQuantum/Latin.yml

@@ -0,0 +1,13 @@
+extends: substitution
+message: "Use '%s' instead of '%s'."
+link: 'https://www.ibm.com/developerworks/library/styleguidelines/index.html#wordlist'
+ignorecase: true
+level: error
+nonword: true
+action:
+  name: replace
+swap:
+  '\b(?:eg|e\.g\.)[\s,]': for example
+  '\b(?:ie|i\.e\.)[\s,]': that is
+  '\betc\.': and so on
+  '\bvs\.': versus

test/docs/IBMQuantum/OxfordComma.yml

@@ -0,0 +1,6 @@
+extends: existence
+message: "Use the Oxford comma in '%s'."
+link: 'https://www.ibm.com/developerworks/library/styleguidelines/index.html#N106BF'
+level: suggestion
+tokens:
+  - '(?:[^,]+,){1,}\s\w+\sand'

test/docs/IBMQuantum/Politeness.yml

@@ -0,0 +1,9 @@
+extends: existence
+message: "Don't use '%s'"
+link: 'https://github.com/IBM/ibm-quantum-style-guide/issues/16'
+ignorecase: true
+level: error
+tokens:
+  - please
+  - thanks
+  - thank you

test/docs/IBMQuantum/Repetition.yml

@@ -0,0 +1,6 @@
+extends: repetition
+message: "'%s' is repeated!"
+level: error
+alpha: true
+tokens:
+  - '[^\s]+'

test/docs/IBMQuantum/Spelling.yml

@@ -0,0 +1,5 @@
+extends: spelling
+message: "Unknown word '%s'; fix or add to dictionary."
+level: error
+ignore: 
+  - dictionary.txt