Implement vale in pre-commit

[jorgepiloto]

🐞 Problem
Documentation reviews are a tedious task and need to be automated as possible. Human approval will always be required but we could take advantage of vale during the whole development process.

This tool was proposed in one of the documentation meetings and looks promising. It is not only capable of dealing with programming languages but also with Markup ones.

💡 Solution
Vale is built on top of Go and for the moment, it cannot be integrated with pre-commit. If we want to take advantage of this tool, it should be integrated into our CI/CD pipelines.

[greschd]

Vale is built on top of Go and for the moment, it cannot be integrated with pre-commit.

I think we could probably run it with the repo: local option, which is used to run commands installed on the developer machine (without isolated environment). Of course, it may be somewhat cumbersome if we don't also provide an easy way to install it.

For context, I typically run tools such as mypy from the repo: local, because they need access to the code's Python environment. However, there we can use the usual (extra) dependencies to smoothly set up the tool itself and pin its version.

[jorgepiloto]

I see there is a Vale docker image.

[greschd]

We might also consider adding it to pre-commit (to coordinate any command line options etc.), but with a non-default stage (docs: https://pre-commit.com/#confining-hooks-to-run-at-certain-stages).

That way, developers who have it installed get an easy way to run it (e.g. pre-commit run --hook-stage manual), but if you don't it doesn't prevent you from using pre-commit install.

EDIT: Since this repo is mainly about docs, it may make more sense to run vale by default. For other repositories (more code-centric), not running it by default may be more reasonable.

[jorgepiloto]

Vale was implemented in CI scope by @RobPasMue and @PipKat in pull request #118.

At the moment, we do not provide a way for running Vale locally. Let me rename this issue for targeting this problem.

[RobPasMue]

Vale can indeed be run locally, but requires:

• A local installation of the tool (follow https://vale.sh/docs/vale-cli/installation/#package-managers depending on your package manager.

Once installed, one can run the following commands inside the docs folder (where the config file is located):

vale sync
vale .

You can also run it from the root directory as follows:

vale doc --config=doc/.vale.ini

Ping me if you want further information for implementing this :)