Work around Vale issues#

Some issues that Vale raises may not be considered problematic in PyAnsys projects. This page describes some common workarounds.

Turn Vale off and on#

If Vale flags content as an issue but you know that this content is acceptable, you can use the following directives to turn Vale off before the flagged content and then back on again after it:

.. vale off

This is some text.

.. vale on

As shown in the preceding example, you must insert blank lines to separate the directives for tuning Vale off and on from your documentation content.

In an Markdown (MD) file, the syntax for these two Vale directives looks like this:

<!-- vale off -->

This is some text.

<!-- vale on -->

Insert non-breaking spaces#

Vale displays a warning when it thinks a non-breaking space should be used in an RST or MD file. Here is how you insert a non-breaking space:

In an RST file, use the Unicode character U+00A0 for a non-breaking space. You can insert it by typing   or &#160.
In an MD file, use the HTML entity   or the Unicode character U+00A0 for a non-breaking space. You can insert it by typing &#160.

For example, you can insert a non-breaking space between two words in either an RST or MD file by typing word1 word2.

Allow the use of a word not allowed by the Google word list#

Based on an implemented Google word list, Vale raises warnings when certain words, such as “check” and “functionality,” are used. While you can ignore Vale warnings, if the list of warnings becomes long, it can become annoying to have to scroll through them to find the errors that you must address.

To have Vale accept your use of a word that is raising a warning, you can add the word to the accept.txt file in the doc/styles/config/vocabularies/ANSYS directory.

Turn off a particular style rule#

Vale implements many Google style rules, which you can see in the YML files in the doc/styles/Google directory. If necessary, you can turn off a particular rule.

For example, the rule in the Colons.yml file specifies that a lowercase letter must follow a colon. However, in some cases, you might want to allow uppercase letters to follow colons.

While you could turn Vale off and on each time an error is raised for this colon style violation, this approach is cumbersome if there are many such errors. Thus, you can turn off the Google style rule that is causing Vale to raise the error:

Go the doc directory and open the vale.ini file.

Locate this content:

# Apply the following styles
BasedOnStyles = Vale, Google

Add a line to turn off the Google rule about requiring a lowercase letter after a colon:
```
# Apply the following styles
BasedOnStyles = Vale, Google
Google.Colons = NO
```

Tell Vale to ignore inline roles#

If Vale raises errors about content within inline roles, such as ref, file, and class, implement a workaround by telling Vale to ignore this content. Simply follow the previous steps, adding the TokenIgnores argument to the end of the vale.ini file:

# Apply the following styles
BasedOnStyles = Vale, Google
Google.Colons = NO

# Ignore content in inline roles
TokenIgnores = (:.*:`.*`)|(<.*>)

Clear files generated by local building of the documentation#

When you build documentation locally, the build process generates _autosummary files in one or more _autosummary directories. When you next run Vale locally, it finds these files and checks them, which likely results in it identifying lots of issues.

To clear _autosummary files, clean the doc folder:

If the Ansys Python Manager and the Administrator window are not open, open them. For more information, see Install and use the Ansys Python Manager.
In the Administrator window, use the cd command to go to the root folder.
Run this Git command:
```
git clean -f -d -x doc
```
Use the cd command to go to the doc directory.
Run this Vale command to install the latest rules for the Google style guidelines locally:
```
vale sync
```
Run this Vale command to check all RST and MD files in the doc directory:
```
vale .
```

If _autosummary directories or files are still present, you have accidentally pushed them to the repository. You want to delete these directories or files from your local branch and push this change to the repository so that they are also removed from it.

Specify a specific Vale version#

If you push your changes to a PR and Vale raises lots of inappropriate errors about titles not being in sentence case when they are already in title case, in the .github/workflows directory, open the ci_cd.yml file and then update the “Documentation Style Check” to use Vale version 3.4.1:

docs-style:
  name: Documentation Style Check
  runs-on: ubuntu-latest
  steps:
    - name: PyAnsys documentation style checks
      uses: ansys/actions/doc-style@v6
      with:
        token: ${{ secrets.GITHUB_TOKEN }}
        vale-version: "3.4.1"