| Message ID | 20230314114431.1096972-1-peter.maydell@linaro.org |
|---|---|
| State | Superseded |
| Headers | show |
| Series | docs/sphinx/kerneldoc.py: Honour --enable-werror | expand |
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>
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
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
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)
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(-)