Re: [PATCH] docs/sphinx/kerneldoc.py: Honour --enable-werror

[Peter Maydell <peter.maydell@linaro.org>]

[-- Attachment #1: Type: text/plain, Size: 1629 bytes --]

On Thu, 16 Mar 2023 at 13:40, Laurent Vivier <laurent@vivier.eu> wrote:
>
> Le 14/03/2023 à 12:44, Peter Maydell a écrit :
> > Currently, the kerneldoc Sphinx plugin doesn't honour the
> > --enable-werror configure option, so its warnings are never fatal.
> > This is because although we do pass sphinx-build the -W switch, the
> > warnings from kerneldoc are produced by the scripts/kernel-doc script
> > directly and don't go through Sphinx's "emit a warning" function.
> >
> > When --enable-werror is in effect, pass sphinx-build an extra
> > argument -Dkerneldoc_werror=1.  The kerneldoc plugin can then use
> > this to determine whether it should be passing the kernel-doc script
> > -Werror.
> >
> > We do this because there is no documented mechanism for
> > a Sphinx plugin to determine whether sphinx-build was
> > passed -W or not; if one is provided then we can switch to
> > that at a later date:
> > https://github.com/sphinx-doc/sphinx/issues/11239
> >
> > Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
> > ---
> > NB: we need to land the fix for the current outstanding
> > warning before this one can go in...
> >
https://lore.kernel.org/qemu-devel/20230310103123.2118519-11-alex.bennee@linaro.org/
> > ---
> >   docs/meson.build         | 2 +-
> >   docs/sphinx/kerneldoc.py | 5 +++++
> >   2 files changed, 6 insertions(+), 1 deletion(-)

> I've applied it to my trivial-patches branch,
> but if you want to apply it via some doc or misc branches, let me know.

Trivial is fine, but make sure you've put in the fix for
the outstanding warning first :-)

-- PMM

[-- Attachment #2: Type: text/html, Size: 2261 bytes --]