Fail docs build on warnings

[tomazfernandes]

Context

• We recently had a docs formatting regression that would have been caught if the docs build failed on warnings.
• There is already a fail-on-warning configuration, but it is currently disabled/commented out.

Proposal

• Re-enable fail-on-warning for docs.
• Fix the current warnings so CI stays green going forward.

Why

• This prevents formatting regressions from being merged by failing the docs build on warnings.

[tomazfernandes]

@maciejwalkowiak I opened this issue as follow-up to the recent docs formatting regression (see #1570).

We already have configuration to fail the docs build on AsciiDoc warnings, but it looks like it’s currently commented out and the docs are not built as part of the PR CI.

#1572 re-enables fail-on-warning, fixes the existing warnings to keep CI green, and adds a docs validation job to the CI workflow. This should catch issues like unterminated blocks earlier. I verified this would have flagged the regression, and added a brief before/after in the PR comments for context.

Also, what’s the usual way to update the published docs when a docs fix lands after a release?
Is there a republish workflow, or is a 4.0.1 patch release typically required?