GitHub - IBM/ibm-quantum-style-guide: Quantum-specific documentation styleguide
source link: https://github.com/IBM/ibm-quantum-style-guide
Go to the source link to view the article. You can view the picture content, updated content and better typesetting reading experience. If the link is broken, please click the button below to view the snapshot at that time.
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.
Using Vale in your repo
You can use the qiskit-ibm-runtime
integration as a
reference.
-
Install Vale locally.
ℹ️ If you work with reStructuredText, make sure
docutils
is installed andrst2html
is on yourPATH
. -
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.
-
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
-
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.
Recommend
About Joyk
Aggregate valuable and interesting links.
Joyk means Joy of geeK