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?
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.
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.
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?
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
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!
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.
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.
