IBM Quantum style guide

This repo contains Vale-compatible rules implementing the IBM Quantum style guide. Use these rules with Vale to help keep your writing consistent with our style suggestions. These rules are based on the IBM style guide, with extra rules specific to quantum computing.

Using Vale in your repo

You can use the qiskit-ibm-runtime integration as a reference.

1. Install Vale locally.

   ℹ️ If you work with reStructuredText, make sure docutils is installed and rst2html is on your PATH.

2. Download the latest release, copy the "IBMQuantum" directory somewhere in your repo (usually the tests folder), and add a configuration file:

   # This goes in a file named either `.vale.ini` or `_vale.ini`.
   StylesPath = path/to/dir  # should point to parent of `IBMQuantum` directory 
   
   [*.md]
   BasedOnStyles = IBMQuantum

   See Vale's usage docs for more information.

3. Test your files using

   vale <filepath>

   for markdown, rst, and HTML. For notebooks, use nbQA with the following command:

   nbqa vale <path-to-notebook> --nbqa-shell --nbqa-md

   You can use a shell script to lint everything, for example:

   #!/bin/bash
   
   # Lint .rst and .md using plain Vale
   cd ./docs
   vale .
   
   # Use nbQA to lint notebooks
   notebooks=$(find . -name "*.ipynb" -not -name "*checkpoint*")
   python -m nbqa vale ${notebooks} --nbqa-shell --nbqa-md

4. Run this check on pull request using a GitHub action.

Ignoring rules

If you find a false positive, please make an issue.

If the rule is working correctly but you still want to disable it, you can turn specific rules off for sections of text using these comments:

<!-- vale IBMQuantum.RuleName = NO -->

This text will not trigger RuleName

<!-- vale IBMQuantum.RuleName = YES -->

If the rule isn't appropriate for your repo, you can disable it everywhere by adding this line to your .vale.ini:

IBMQuantum.RuleName = NO

Keeping up to date

To have GitHub notify you on new releases, from the repo page click "Watch" in the top-right corner. Then choose "custom > releases".

---

This repo is a fork of errata-ai/IBM.