-
Notifications
You must be signed in to change notification settings - Fork 160
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Use Vale to lint docs writing #739
Conversation
Co-authored-by: Rebecca Dimock <[email protected]>
Check out this pull request on See visual diffs & provide feedback on Jupyter Notebooks. Powered by ReviewNB |
Pull Request Test Coverage Report for Build 4353319540
💛 - Coveralls |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Looks good on my end - If @beckykd is on board with these changes, we can merge
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Excited to add this process!
* Add writing linting with Vale * Lint docs using Vale rules Co-authored-by: Rebecca Dimock <[email protected]> * Add Vale tests to CI * Run black code formatting * Remove unneeded echo statements * Update PATH --------- Co-authored-by: Rebecca Dimock <[email protected]>
* Add writing linting with Vale * Lint docs using Vale rules Co-authored-by: Rebecca Dimock <[email protected]> * Add Vale tests to CI * Run black code formatting * Remove unneeded echo statements * Update PATH --------- Co-authored-by: Rebecca Dimock <[email protected]>
* Add writing linting with Vale * Lint docs using Vale rules Co-authored-by: Rebecca Dimock <[email protected]> * Add Vale tests to CI * Run black code formatting * Remove unneeded echo statements * Update PATH --------- Co-authored-by: Rebecca Dimock <[email protected]>
Summary
Uses Vale to lint writing in the docs. The most notable impact is the ability to catch spelling errors during CI, but this tool can also help enforce writing style rules.
To try it, install Vale and run
(you may also need to
pip install docutils
if you don't have it already).Most developers should be able to ignore this test (that is, no need to install Vale), and should only be impacted if a documentation change introduces an error, which is usually easily fixable.
Details and comments
The rules used are from IBM/ibm-quantum-style-guide.
Similar to pylint, you can turn off rules for specific sections using comments. Please make an issue if a rule is not working correctly so we can improve it.
How to read this PR
I've split this into three separate commits to make review easier:
In collaboration with @beckykd.