Failing Sphinx builds on WARN with the package docs

Since we’ve started building package docs in GHA the logs from each run are public and now reveal all the WARNINGs and ERRORs from RST in ansible/ansible-documentation as well as from all the modules and collections and other bits. @felixfontein and I were chatting about it a bit in this issue.

There’s obvs some cleanup work to do to get the builds running cleanly but let’s say we get package docs to build with zero issues. We could then configure Sphinx to fail on WARN messages in the logs. If we were doing nightly builds of devel, we could start catching those issues earlier and getting them fixed promptly.

Considering some of those errors come from community collections, would it be possible to make package inclusion conditional on no busted doc builds? Or is that just crazy talk?

1 Like

Ah yes… it was glorious pre-collections when acozine and I got all the warnings down to zero (and kept on it after that to keep it that way). We didn’t fail on WARNs but we did keep an eye and fix when they came up.

So if we do get to the state where they are all fixed, then I’d be up for some kind of testing/validation that ensures it stays that way for sure.

1 Like

General consensus in today’s DaWGs meeting is yes, would be good both to clean up all of these warnings AND find a way as suggested here to keep that count down to zero in the future as well.


Excellent. I’ll send a PR to update that build workflow to start running nightly so we can get it going. I’ll try and narrow down some of those warnings too. A good few of them we can fix in the docs repo but there are several from collections. It’s mostly things like duplicate labels and formatting cleanup.

Some problems will go away once Improve error handling/rendering by felixfontein · Pull Request #289 · ansible-community/antsibull-docs · GitHub is merged and a new release is made with it. (There’s also Collection links: allow to mention forums by felixfontein · Pull Request #288 · ansible-community/antsibull-docs · GitHub waiting for reviews.)

And then there’s Linter: prevent option/return value/... names which only differ by case · Issue #291 · ansible-community/antsibull-docs · GitHub which could help preventing several of the other warnings currently shown. Having different options with almost the same name looks like a bug in most cases. (Likely one of them should be an alias of the others, either deprecated or not, instead of having separate options.)


Once we get the list to zero, let’s make the warnings fatal in CI, that’s the way to stop this reoccurring.

What help is needed to get these fixed? Is this a good topic/focus area for next DaWGS?

This should cause a CI error. The module docs are likely getting out of sync as people update the wrong one.
Do we have a way to run an updated version of validate-modules across all the Ansible Collections · GitHub (pre-merge) to generate a list of things to fix?

Once we get the list to zero, let’s make the warnings fatal in CI, that’s the way to stop this reoccurring.

Yes, that’s what I’d like to do. We can add SPHINXOPTS="-W" to the package doc build nightlies and get matrix notifications.


Last week the DaWGs agreed to move to the forum for building the weekly agenda. So I added the dawgs-meeting tag to this topic and we’ll discuss it in…a little over an hour :slight_smile:

So… Part of this whole thing was setting a schedule for the build workflow, which we did earlier this week. However the scheduled builds are failing because I did not fully understand that the input defaults take affect only when the workflow is triggered manually. When run on a schedule the input defaults are null and the job fails. Yay!

I’ve created an issue for it: Nightly builds failing with no default values · Issue #1682 · ansible/ansible-documentation · GitHub

Seems we have a couple of options and I thought I’d reply to this thread for visibility. We can either add some expressions to the build job to set the defaults for scheduled runs or we can create a separate, simplified workflow without inputs that only runs the devel branch of the ansible/ansible-documentation repository.

The second option seems better to me because it avoids adding more complexity to the workflow. Additionally if we have a separate job for then we can enable strict builds for just that, which means we can still build and deploy the package docs with the existing workflow even if there are warnings.

Any thoughts?

I’m a bit of two minds on this one.

On the one hand adding default values to the existing job ensures that we have the same steps running on a schedule and at deploy time without having to keep them in sync manually.

On the other, I totally agree with your points about not adding complexity, and keeping the flexibility for forcing strict on scheduled runs but allowing looser rules for deploy if/as needed.

My initial instinct would be to “split the difference” and try to keep it as one job, and use the complexity we do add to also give us the flexibility to only force strict builds on a schedule. But I’d have to dig into how complex that is to logic out, and if the group thinks its a reasonable approach.

I like the approach @Lyle_McKarns is taking in the issue - try to integrate it into one workflow and see how hard/complex it gets.