Page MenuHomeSoftware Heritage

Building the documentation should not show any warning.
Closed, ResolvedPublic

Description

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.

Event Timeline

anlambert triaged this task as Normal priority.Feb 3 2020, 3:56 PM
anlambert created this task.

You can check if there is currently some warnings issued during the documentation build by following this link. Every reported warnings should be fixed.

The link doesn't work while building. Maybe try using lastCompletedBuild instead of lastBuild
Also, I don't see an errors.log file in the recent builds. Looks like the code has been altered.

I'm confused about the status of this task. I've just rebuilt the docs for docs.s.o and it says "build succeeded, 83 warnings.". So is the fix for this not yet "deployed" somehow? Also, why is the build succeeding even with all those warnings? Because as long as that's the case, we will for sure keep reintroducing warnings as time goes by.

In T2265#63475, @zack wrote:

I'm confused about the status of this task. I've just rebuilt the docs for docs.s.o and it says "build succeeded, 83 warnings.". So is the fix for this not yet "deployed" somehow? Also, why is the build succeeding even with all those warnings? Because as long as that's the case, we will for sure keep reintroducing warnings as time goes by.

Some swh packages with the doc fixes did not get tagged yet so the warnings in the publish doc build, check the dev build instead.

Also, why is the build succeeding even with all those warnings

We do not use -W option of sphinx-build in the publish build.

Because as long as that's the case, we will for sure keep reintroducing warnings as time goes by.

T3258 should help to avoid introducing new doc build errors, once we found a decent solution.

Thanks for the feedback.

We do not use -W option of sphinx-build in the publish build.

Is there a reason for not doing it?

Is there a reason for not doing it?

I guess the reason it was not activated is that we wanted to publish updated doc regardless sphinx warnings.

Once we managed to build and check (local package) doc on each diff, we could activate the -W option
for the publish job too I think.

We need more loud warnings of doc build issues (eg. broken references) first.