Let RTD fail on warnings

[ewu63]

Description of feature

Ideally, we turn on nitpicky and convert all warnings to errors.

Potential solution

The first is easy to do since we can do it in conf.py, but not the latter which is only supported via SPHINXOPTS = -W --keep-going.
AFAIK the only way to do the second would be to set this option in a configuration file, which will be annoying since we'd have to add it to every single docs repo.

Alternatively, we can easily add another CI job which just installs the docs dependencies, builds the docs, and exits with the correct exit code. There will be some duplication but maybe that's a good compromise?

[eirikurj]

You can also just modify the Makefile in the project directly and add SPHINXOPTS = -W --keep-going. These options will then also be enforced when building locally, but you still need to go and add this to every repo.
Having two jobs (Azure and RTD) compiling the docs may be somewhat confusing to people (and waste of resources). None of these options (RTD config file, edit the Makefile, CI job) are ideal, they all have some compromises. Are there any other benefits of the RTD file that we may use in the future?

[ewu63]

RTD does not call the Makefile, it directly invokes sphinx-build---see here. I am still okay with adding those SPHINXOPTS to every repo since it's an existing file and helps with local debugging anyways, but it would be nice to do this in an automated way.

I think I can also be convinced to add the config yaml file to all repos, since it will just sit there and probably does not need to be modified much. Other things will be added too, since using the file will cause RTD to ignore all settings we configured on the web. That includes the following:

• version
• python.install.requirements
• build.os
• build.tools.python
• sphinx.configuration
• sphinx.fail_on_warning

There are probably more that we want to migrate from the web interface.

[eirikurj]

Ahh, you are right, I forgot that it ignored it. In any case, it would make sense to include it in the Makefile if we are introducing this in the RTD build. I am also fine with adding the RTD config file to the repos.

[ewu63]

I have added the nitpicky option as part of #9, I think this will go a long way since it will show any missing links as red during the build process, so hopefully people are checking this locally. Having the CI fail based on this would be the next step, but it is annoying that this cannot be configured from Python/Makefile, only from the YAML file.