Building the documentation should not show any warning.
We must ensure that no Sphinx warnings are issued when building the development documentation to ensure a clean HTML output.
That task is here to remind that fact and should not be closed as new warnings will necessarily appear as the Software heritage codebase evolves.
You can check if there is currently some warnings issued during the documentation build by following this link. Every reported warnings should be fixed.
Here are some information to execute locally the full swh documentation build in the same was as it is done by the corresponding CI job on Jenkins.
Assuming that you have already followed these instructions to setup the swh development environment, go to the swh-docs/docs
folder and
execute the following commands: make clean distclean && SPHINXOPTS='-W -q --keep-going -w errors.log' tox -e sphinx-dev
.
All current warnings and errors will be dumped into the swh-docs/docs/errors.log
file.
Migrated from T2265 (view on Phabricator)