[PATCH 1/1] docs: let sphinx-build fail on warnings

[Felix Moessbauer]

Warnings during the documentation build are always critical, as they
might indicate broken references or failed generators that result in a
broken documentation.

Signed-off-by: Felix Moessbauer <felix.mo...@siemens.com>
---
docs/Makefile | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/Makefile b/docs/Makefile
index 5de69c718..02491e914 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -10,7 +10,7 @@ BUILDDIR = _build
# Internal variables.
PAPEROPT_a4 = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees --fail-on-warning $(PAPEROPT_$(PAPER)) $(WARNOPTS) $(SPHINXOPTS) .
# the i18n builder cannot share the environment and doctrees with the others
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .

--
2.53.0

[Jan Kiszka]

Does not help with invalid references at least:

https://app.readthedocs.org/projects/kas/builds/33246423/

Jan

--
Siemens AG, Foundational Technologies
Linux Expert Center

[Jan Kiszka]

...which is due to our own code: We swallow that error and just return
an empty string, don't we?

But also that "WARNING: Option list ends without a blank line;
unexpected unindent" is not causing any failure.

[MOESSBAUER, Felix]

On Mon, 2026-06-22 at 12:04 +0200, Jan Kiszka wrote:
> On 22.06.26 12:00, 'Jan Kiszka' via kas-devel wrote:
> > On 22.06.26 11:12, Felix Moessbauer wrote:
> > > Warnings during the documentation build are always critical, as they
> > > might indicate broken references or failed generators that result in a
> > > broken documentation.
> > >
> > > Signed-off-by: Felix Moessbauer <felix.mo...@siemens.com>
> > > ---
> > > docs/Makefile | 2 +-
> > > 1 file changed, 1 insertion(+), 1 deletion(-)
> > >
> > > diff --git a/docs/Makefile b/docs/Makefile
> > > index 5de69c718..02491e914 100644
> > > --- a/docs/Makefile
> > > +++ b/docs/Makefile
> > > @@ -10,7 +10,7 @@ BUILDDIR = _build
> > > # Internal variables.
> > > PAPEROPT_a4 = -D latex_paper_size=a4
> > > PAPEROPT_letter = -D latex_paper_size=letter
> > > -ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
> > > +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees --fail-on-warning $(PAPEROPT_$(PAPER)) $(WARNOPTS) $(SPHINXOPTS) .

I just noticed that WARNOPTS is a left-over from a refactoring...
Will fix it in v2.

> > > # the i18n builder cannot share the environment and doctrees with the others
> > > I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
> > >
> >
> > Does not help with invalid references at least:
> >
> > https://app.readthedocs.org/projects/kas/builds/33246423/
> >
>
> ...which is due to our own code: We swallow that error and just return
> an empty string, don't we?

Right, the error is swallowed before it even reaches sphinx. This is
fixed in the port to a plugin instead of the shell script.

>
> But also that "WARNING: Option list ends without a blank line;
> unexpected unindent" is not causing any failure.

Does this depend on the sphinx-build version? I have 9.1.0 which
correctly detects the error and emits 1:

make html
[...]
_build/kas-container-usage-options.inc:27: WARNING: Option list ends
without a blank line; unexpected unindent. [docutils]
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
copying assets...
copying static files...
Writing evaluated template result to
/home/user/src/kas/docs/_build/html/_static/language_data.js
Writing evaluated template result to
/home/user/src/kas/docs/_build/html/_static/documentation_options.js
Writing evaluated template result to
/home/user/src/kas/docs/_build/html/_static/basic.css
Writing evaluated template result to
/home/user/src/kas/docs/_build/html/_static/js/versions.js
copying static files: done
copying extra files...
copying extra files: done
copying assets: done
writing output... [100%] userguide/project-configuration
generating indices... genindex py-modindex done
highlighting module code... [100%] kas.repos
writing additional pages... search done
dumping search index in English (code: en)... done
dumping object inventory... done
build finished with problems, 1 warning (with warnings treated as
errors).
make: *** [Makefile:53: html] Error 1

Or is it a RTD specialty?

Felix

[Jan Kiszka]

I'm referring to
https://github.com/siemens/kas/blob/567950bc53c0106acc53076628c82cf9796fe7c8/docs/_ext/sphinx_kas_schema.py#L70
- the exception is consumed, not forwarded. This is not changing in any
of your pending patches as they do not touch this pre-existing plugin.

You can see in the logs that we are on sphinx 9.1.0 on RTD as well.

[MOESSBAUER, Felix]

Hmm... we indeed catch the error right after raising it. Will send a
fix for this. Still I'm wondering why a missing key leads to error code
1 on my system (with the current implementation), while not on RTD.

Investigating...

Felix