[PATCH] dts: fix API doc build warnings

[PATCH] dts: fix API doc build warnings

[Luca Vizzarro]

Sphinx-autodoc issues warnings about some symbols due to bad autodoc
"automock"ing when optional dependencies are missing.

The current meson setup allows to treat warnings as errors, halting the
process and exiting early. Given these warnings should be ignored, this
patch removes this behavior. Until optional dependencies are enforced,
warnings for DTS API docs will be checked manually as part of the DTS
approval process.

Fixes: 6597fa4a30ad ("dts: add autodoc Pydantic")

Signed-off-by: Luca Vizzarro <luca.vizzarro@arm.com>
---
 doc/api/dts/meson.build | 3 ---
 1 file changed, 3 deletions(-)

diff --git a/doc/api/dts/meson.build b/doc/api/dts/meson.build
index fc147f13f3..8a6d061879 100644
--- a/doc/api/dts/meson.build
+++ b/doc/api/dts/meson.build
@@ -12,9 +12,6 @@ if python_ver_satisfied != 0
 endif
 
 extra_sphinx_args = ['-E', '-c', join_paths(doc_source_dir, 'guides')]
-if get_option('werror')
-    extra_sphinx_args += '-W'
-endif
 
 # DTS docs are generated inside main Doxygen docs build directory
 # DTS docs relies on main docs to install it so does not define install dir
-- 
2.43.0

Re: [PATCH] dts: fix API doc build warnings

[Thomas Monjalon]

20/11/2024 15:41, Luca Vizzarro:
> Sphinx-autodoc issues warnings about some symbols due to bad autodoc
> "automock"ing when optional dependencies are missing.
> 
> The current meson setup allows to treat warnings as errors, halting the
> process and exiting early. Given these warnings should be ignored, this
> patch removes this behavior.

So the patch is not fixing warnings, it allows them.
I will change the title.

> Until optional dependencies are enforced,
> warnings for DTS API docs will be checked manually as part of the DTS
> approval process.

No, optional dependencies should never be enforced.

[...]
> -if get_option('werror')
> -    extra_sphinx_args += '-W'
> -endif

Re: [PATCH] dts: fix API doc build warnings

[Thomas Monjalon]

20/11/2024 16:05, Thomas Monjalon:
> 20/11/2024 15:41, Luca Vizzarro:
> > Sphinx-autodoc issues warnings about some symbols due to bad autodoc
> > "automock"ing when optional dependencies are missing.
> > 
> > The current meson setup allows to treat warnings as errors, halting the
> > process and exiting early. Given these warnings should be ignored, this
> > patch removes this behavior.
> 
> So the patch is not fixing warnings, it allows them.
> I will change the title.
> 
> > Until optional dependencies are enforced,
> > warnings for DTS API docs will be checked manually as part of the DTS
> > approval process.
> 
> No, optional dependencies should never be enforced.
> 
> [...]
> > -if get_option('werror')
> > -    extra_sphinx_args += '-W'
> > -endif

It makes the CI issue disappear.

Applied with this modified message, thanks for fixing quickly:

    doc: allow warnings in Sphinx for DTS
    
    Sphinx-autodoc issues warnings about some symbols due to bad autodoc
    "automock"ing when optional dependencies are missing:
    
    Warning, treated as error:
            Failed to get a method signature for
            framework.config.TestSuiteConfig.convert_from_string:
            <classmethod(<function TestSuiteConfig.convert_from_string
            at 0x7f1a4ec10790>)> is not a callable object
    
    The current meson setup allows to treat warnings as errors, halting the
    process and exiting early. Given these warnings should be ignored, this
    patch removes this behavior. Until optional dependencies are detected,
    warnings for DTS API docs will be checked manually as part of the DTS
    approval process.
    
    Fixes: 6597fa4a30ad ("dts: add autodoc Pydantic")
    
    Signed-off-by: Luca Vizzarro <luca.vizzarro@arm.com>

Re: [PATCH] dts: fix API doc build warnings

[Patrick Robb]

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

Thanks Luca, Thomas,

I see Thomas just applied it to main, but I'll mention I tested with meson
werror and I think this fix is appropriate.

This is a good reminder for us to always build with --werror

On Wed, Nov 20, 2024 at 10:54 AM Thomas Monjalon <thomas@monjalon.net>
wrote:

> 20/11/2024 16:05, Thomas Monjalon:
> > 20/11/2024 15:41, Luca Vizzarro:
> > > Sphinx-autodoc issues warnings about some symbols due to bad autodoc
> > > "automock"ing when optional dependencies are missing.
> > >
> > > The current meson setup allows to treat warnings as errors, halting the
> > > process and exiting early. Given these warnings should be ignored, this
> > > patch removes this behavior.
> >
> > So the patch is not fixing warnings, it allows them.
> > I will change the title.
> >
> > > Until optional dependencies are enforced,
> > > warnings for DTS API docs will be checked manually as part of the DTS
> > > approval process.
> >
> > No, optional dependencies should never be enforced.
> >
> > [...]
> > > -if get_option('werror')
> > > -    extra_sphinx_args += '-W'
> > > -endif
>
> It makes the CI issue disappear.
>
> Applied with this modified message, thanks for fixing quickly:
>
>     doc: allow warnings in Sphinx for DTS
>
>     Sphinx-autodoc issues warnings about some symbols due to bad autodoc
>     "automock"ing when optional dependencies are missing:
>
>     Warning, treated as error:
>             Failed to get a method signature for
>             framework.config.TestSuiteConfig.convert_from_string:
>             <classmethod(<function TestSuiteConfig.convert_from_string
>             at 0x7f1a4ec10790>)> is not a callable object
>
>     The current meson setup allows to treat warnings as errors, halting the
>     process and exiting early. Given these warnings should be ignored, this
>     patch removes this behavior. Until optional dependencies are detected,
>     warnings for DTS API docs will be checked manually as part of the DTS
>     approval process.
>
>     Fixes: 6597fa4a30ad ("dts: add autodoc Pydantic")
>
>     Signed-off-by: Luca Vizzarro <luca.vizzarro@arm.com>
>
>
>
>
>

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