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

[Laurent Vivier]

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(-)
>
> diff --git a/docs/meson.build b/docs/meson.build
> index bb72c10ea8c..f220800e3e5 100644
> --- a/docs/meson.build
> +++ b/docs/meson.build
> @@ -7,7 +7,7 @@ if sphinx_build.found()
>     SPHINX_ARGS = ['env', 'CONFDIR=' + qemu_confdir, sphinx_build, '-q']
>     # If we're making warnings fatal, apply this to Sphinx runs as well
>     if get_option('werror')
> -    SPHINX_ARGS += [ '-W' ]
> +    SPHINX_ARGS += [ '-W', '-Dkerneldoc_werror=1' ]
>     endif
>   
>     # This is a bit awkward but works: create a trivial document and
> diff --git a/docs/sphinx/kerneldoc.py b/docs/sphinx/kerneldoc.py
> index bf442150165..72c403a7379 100644
> --- a/docs/sphinx/kerneldoc.py
> +++ b/docs/sphinx/kerneldoc.py
> @@ -74,6 +74,10 @@ def run(self):
>           # Sphinx versions
>           cmd += ['-sphinx-version', sphinx.__version__]
>   
> +        # Pass through the warnings-as-errors flag
> +        if env.config.kerneldoc_werror:
> +            cmd += ['-Werror']
> +
>           filename = env.config.kerneldoc_srctree + '/' + self.arguments[0]
>           export_file_patterns = []
>   
> @@ -167,6 +171,7 @@ def setup(app):
>       app.add_config_value('kerneldoc_bin', None, 'env')
>       app.add_config_value('kerneldoc_srctree', None, 'env')
>       app.add_config_value('kerneldoc_verbosity', 1, 'env')
> +    app.add_config_value('kerneldoc_werror', 0, 'env')
>   
>       app.add_directive('kernel-doc', KernelDocDirective)
>   

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.

Thanks,
Laurent