docs/meson.build | 2 +- docs/sphinx/kerneldoc.py | 5 +++++ 2 files changed, 6 insertions(+), 1 deletion(-)
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)
--
2.34.1Le 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
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
Le 16/03/2023 à 14:42, Peter Maydell a écrit : > > > On Thu, 16 Mar 2023 at 13:40, Laurent Vivier <laurent@vivier.eu <mailto: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 > <https://github.com/sphinx-doc/sphinx/issues/11239> > > > > > > Signed-off-by: Peter Maydell <peter.maydell@linaro.org <mailto: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/ > <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 :-) I didn't take this one but: https://www.mail-archive.com/qemu-devel@nongnu.org/msg949558.html Is it ok? Thanks, Laurent
On Thu, 16 Mar 2023 at 15:16, Laurent Vivier <laurent@vivier.eu> wrote: > > Le 16/03/2023 à 14:42, Peter Maydell a écrit : > > > > > > On Thu, 16 Mar 2023 at 13:40, Laurent Vivier <laurent@vivier.eu <mailto: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 > > <https://github.com/sphinx-doc/sphinx/issues/11239> > > > > > > > > Signed-off-by: Peter Maydell <peter.maydell@linaro.org <mailto: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/ > > <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 :-) > > I didn't take this one but: > > https://www.mail-archive.com/qemu-devel@nongnu.org/msg949558.html Yeah, that one has the same effect. -- PMM
On 14/03/2023 12.44, Peter Maydell wrote: > 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(-) Reviewed-by: Thomas Huth <thuth@redhat.com>
© 2016 - 2024 Red Hat, Inc.