4. Setting up tests

Now that Travis can tap into the repository, we can prepare task for it to perform. An essential part is testing. The first obvious test is Can the docs be built?. Other tests are usually:

• Is the spelling ok?

• Are the docs matching my style guide?

We can tests these using Vale. It is a command line tool that checks user-defined patterns. Let’s set it up.

4.1. Defining styles

To understand how to define styles, see the official docs.

Let’s define 3 styles: - Forbid please or thank you. - Forbid double spaces. - Forbid the use of uncertain tenses (should, ought…).

1. At the root of your project, create a folder styles.

2. Create a file named Polite.yml that contains:

   extends: existence
   message: 'Do not use “%s” in technical documentation.'
   level: error
   ignorecase: true
   tokens:
     - please
     - thank you
   

3. Create a file named Spacing.yml that contains:

   extends: existence
   message: "'%s' has a double space."
   level: error
   nonword: true
   tokens:
     - '[a-z][.?!][A-Z]'
     - '[.?!] {2,}[A-Z]'
     - '[a-zA-Z]  [A-Za-z]'
   

4. Create a file named Tenses.yml that contains:

   extends: existence
   message: "'%s' is an uncertain tense. Use the present instead."
   ignorecase: true
   level: error
   tokens:
     - ought
     - shall
   

5. Add these 3 files to the styles folder.

6. At the root of you project, create a file named .vale.ini that contains:

   StylesPath = ./styles
   MinAlertLevel = suggestion
   
   [*.{md,rst}]
   BasedOnStyles = mystyles
   
   vale.Redundancy = YES
   vale.Repetition = YES
   vale.GenderBias = YES
   

There are compilations of styles available, see Vale styles.

4.2. Running Vale

We’ve defined some styles, let’s check if our documentation contains issues:

1. Install Vale.

2. Open the terminal to your project folder and run:

   vale source
   

Vale reports the errors in your project, if any.

Note

Vale errors do not prevent Sphinx from building.

Next step: Publishing the docs with Travis.