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

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

[Peter Maydell]

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.1

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

[Thomas Huth]

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>

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

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

[Peter Maydell]

[-- 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 --]

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

[Laurent Vivier]

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

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

[Peter Maydell]

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