Odoo Documentation Vale Prose Linter

This project contains the Vale configuration for linting prose on RST files in the Odoo documentation.

Alert Levels

• 🔵 Suggestion: Double check this– but not required to fix.
• 🟡 Warning: This should probably be fixed.
• 🔴 Error: This should absolutely be fixed.

Odoo Styles

• 🔴 Alt Tag: Alt tags should end in a period.
• 🟡 App Names: Odoo app names should use bold formatting.
• 🟡 Avoid: Don't use phrases like "obviously, simply, quickly".
• 🟡 Common Nouns: Don't capitalize common nouns (unless directly referring to the UI, or part of active instructions).
• 🟡 Contraction: Avoid using contractions whenever possible.
• 🟡 Future Tense: Avoid writing in future tense.
• 🔵 Icons: The preferred descriptor for each icon.
• 🟡 Image Align: Consider removing :align: attribute from images.
• 🔴 Nonwords: Common typos of English words.
• 🟡 Optional Plurals: Avoid writing a sentence that adds an optional plural (s) to words.
• 🟡 Ordinals: Write out ordinal numbers.
• 🟡 Pronouns: Avoid using pronouns.
• 🟡 SmartQuotes: Avoid using smartquotes (e.g. “ ” or ‘ ’).
• 🔴 Spacing: Don't use double spaces.
• 🔴 Spelling: Common words that are not part of the default dictionary.
• 🟡 Start Sentence: Avoid starting a paragraph with "But", "There is", or "There are".
• 🔴 WordList: Use the preferred format for these words.

To contribute

If a rule isn't behaving as expected, report it using the "Bug report" template under Issues.

Alternatively, improve existing rules in the styles/Odoo folder, or create new ones. Don't forget to include tests for your rule in the testdata folder.

Install Steps

1. Clone This Repo

First, clone this project to the folder containing your GitHub repos:

github/
├── odoo/
│   └── documentation
└── odoo-vale-linter <-- this repo

Use the following command:

git clone https://github.com/Felicious/odoo-vale-linter.git

2. Install Vale

Follow the installation instructions for your system:

• macOS: brew install vale

• Linux:

  1. In a Terminal, navigate to the odoo-vale-linter repository using: cd path/to/repo.
  2. Run the ./install.sh command, and enter your password when prompted.

This repository uses Vale 3.9.0. Please make sure this version, or a version above.

See the installed Vale version by running vale --version in the terminal.

3. Install Vale VS Code extension

Open VS Code and install the Vale VSCode extension.

Once installed, configure the vale extension to use the Odoo style configurations from this repository.

To do so, open the VS Code Settings and search for Vale.

In the User tab for Vale, select the Enable Spellcheck option in the Vale Settings, as well as set the Readability Problem Location field to Both.

Next, find the Vale CLI: Config field and enter the absolute path to the .vale.ini file from the odoo-vale-linter project.

ℹ️ Tip:
To get the absolute path of the .vale.ini file, open the odoo-vale-linter project in VS Code, right click the .vale.ini file and select Copy Path (do not click Copy Relative Path).

Next, enter the absolute path of Vale in the Vale CLI: Path field.

ℹ️ Tip:
To get the absolute path of vale, type which vale in terminal and copy the result.

macOS

Linux

With these settings, the Vale VSCode extension should now be configured and ready to use with the odoo-vale-linter project to lint prose on RST files.

Update your local repo

Be sure to frequently update your local repo to the latest changes.

First, open a new Terminal window.

Then navigate to the directory containing this repo, for example:

cd github/odoo-vale-linter

Next, pull the latest changes from origin:

git pull origin main

After the pull, your local instance of Vale will enforce the most up-to-date styles.

ℹ️ Tip:
To be notified of changes to this repo, click the Watch button on the top-right of the repo, then select All Activity.

---

Use Vale in VS Code

When an RST file is saved, the alerts that Vale detects display both inline in the RST and in the Problems tab in VS Code.

ℹ️ Tip:
Enable the Problems tab from View --> Problems.

Alert level severity:

1. ℹ️ Suggestion: consider revising; double-check before ignoring.
2. ⚠️ Warning: requires attention; should not be ignored.
3. ❌ Error: critical format that must be addressed.

Either correct the RST or use discretion to ignore the suggestion.