how-to-use-vale.md

(vale)=

How to use Vale

What is Vale?

Vale is a tool that enforces the Google developer documentation style guide on the Ray documentation.

Vale catches typos and grammatical errors. It also enforces stylistic rules like “use contractions” and “use second person.” For the full list of rules, see the configuration in the Ray repository.

How do you run Vale?

How to use the VSCode extension

1. Install Vale. If you don’t use MacOS, see the Vale documentation for instructions.

   brew install vale 

2. Install the Vale VSCode extension by following these installation instructions.

3. VSCode should show warnings in your code editor and in the “Problems” panel.

   

How to run Vale on the command-line

1. Install Vale. If you don’t use MacOS, see the Vale documentation for instructions.

   brew install vale 

2. Run Vale in your terminal

   vale doc/source/data/overview.rst

3. Vale should show warnings in your terminal.

   ❯ vale doc/source/data/overview.rst 
   
       doc/source/data/overview.rst
       18:1   warning     Try to avoid using              Google.We           
                       first-person plural like 'We'.                      
       18:46  error       Did you really mean             Vale.Spelling       
                       'distrbuted'?                                       
       24:10  suggestion  In general, use active voice    Google.Passive      
                       instead of passive voice ('is                       
                       built').                                            
       28:14  warning     Use 'doesn't' instead of 'does  Google.Contractions 
                       not'.                                               
   
   ✖ 1 error, 2 warnings and 1 suggestion in 1 file.
   

Vale doesn’t recognize a word. What do you do?

To add custom terminology, complete the following steps:

1. If it doesn’t already exist, create a directory for your team in .vale/styles/Vocab. For example, .vale/styles/Vocab/Data.
2. If it doesn’t already exist, create a text file named accept.txt. For example, .vale/styles/Vocab/Data/accept.txt.
3. Add your term to accept.txt. Vale accepts Regex.

For more information, see Vocabularies in the Vale documentation.