11. November 2020 4 min read

Use CI to prevent additional Sphinx warnings in your project

I have a habit of fixing warnings when they appear. Although sometimes warnings might seem unjustified I have learned the hard way that suddenly they can be very justified. It is all nice when you are starting the project, but when you join poorly maintained project or just turn new error options for your tool, you are suddenly faced with new warnings. There is never time to fix them, but you don't want to commit new/additional on top of existing.
The solution is in your Continuous Integration pipelines. No matter what you use for building, from GitHub Actions, to GitLab CI, Travis CI, Circle CI, ... there is always a place for the command line tool, that will fail your build when number of warnings is higher (or lower) then expected. Warnings-plugin by Melexis is a project I help maintain that is designed to fail your pipeline if number of warnings is higher or lower than expected.

Setup warnings limit for Sphinx builds

First you need to install the tool through pip in your CI file (or just install it in your Docker container)

pip3 install mlx.warnings

Plugin has two options of usage. The easiest is with command line option, where you add your Sphinx command right after with minimum and maximum number of warnings allowed (or you can use exact number of warnings flag). That basically means any change in number of warnings fails the build. I even have a tendency to make them environment variables, so that they can be different among different stages of the project (maybe development has more/less warnings than release).

Fail your build when there are less than 5 Sphinx warnings:

mlx-warnings --sphinx --min-warnings 5 --command make html

Fail your build when there are more than 5 Sphinx warnings:

mlx-warnings --sphinx --max-warnings 5 --command make html

Fail your build when there are not 5 Sphinx warnings

mlx-warnings --sphinx --exact-warnings 5 --command make html

The second option is that you use the json file. That option is mostly helpful when you have a library that is shared between number of projects and you do not want to set limits in each of the projects, but simply forward the json file from the library to your command. Then content of the json file located in your library would be:

{
    "sphinx": {
        "enabled": true,
        "min": 5,
        "max": 5
    },
}

and the command for the library documentation build would be:

mlx-warnings --config path/to/library/config.json --command make -C path/to/library html

There you are, it is this simple to avoid adding additional warnings to your Sphinx documentation builds and enable only positive progress in your project. Let your projects be warning free.