Re: [PATCH for-5.0? 3/3] kernel-doc: Use c:struct for Sphinx 3.0 and later

[Peter Maydell]

On Sat, 11 Apr 2020 at 19:29, Peter Maydell <address@hidden> wrote:
>
> The kernel-doc Sphinx plugin and associated script currently emit
> 'c:type' directives for "struct foo" documentation.
>
> Sphinx 3.0 warns about this:
>   
> /home/petmay01/linaro/qemu-from-laptop/qemu/docs/../include/exec/memory.h:3: 
> WARNING: Type must be either just a name or a typedef-like declaration.
>   If just a name:
>     Error in declarator or parameters
>     Invalid C declaration: Expected identifier in nested name, got keyword: 
> struct [error at 6]
>       struct MemoryListener
>       ------^
>   If typedef-like declaration:
>     Error in declarator or parameters
>     Invalid C declaration: Expected identifier in nested name. [error at 21]
>       struct MemoryListener
>       ---------------------^
>
> because it wants us to use the new-in-3.0 'c:struct' instead.
>
> Plumb the Sphinx version through to the kernel-doc script
> and use it to select 'c:struct' for newer versions than 3.0.
>
> Fixes: LP:1872113
> Signed-off-by: Peter Maydell <address@hidden>
> ---
>  docs/sphinx/kerneldoc.py |  1 +
>  scripts/kernel-doc       | 16 +++++++++++++++-
>  2 files changed, 16 insertions(+), 1 deletion(-)
>
> diff --git a/docs/sphinx/kerneldoc.py b/docs/sphinx/kerneldoc.py
> index 1159405cb92..3e879402064 100644
> --- a/docs/sphinx/kerneldoc.py
> +++ b/docs/sphinx/kerneldoc.py
> @@ -99,6 +99,7 @@ class KernelDocDirective(Directive):
>                  env.note_dependency(os.path.abspath(f))
>                  cmd += ['-export-file', f]
>
> +        cmd += ['-sphinx-version', sphinx.__version__]

Using sphinx.version() might perhaps be better: it gives you
a tuple of 5 elements rather than a string. OTOH passing the
tuple through to the Perl script without reformulating the
string and re-parsing it in the Perl isn't easy...

thanks
-- PMM