| Message ID | 20200411182934.28678-4-peter.maydell@linaro.org |
|---|---|
| State | Superseded |
| Headers | show |
| Series | Make docs build work with Sphinx 3 | expand |
On Sat, 11 Apr 2020 at 19:29, Peter Maydell <peter.maydell@linaro.org> 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 <peter.maydell@linaro.org> > --- > 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
Peter Maydell <peter.maydell@linaro.org> writes: > 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 <peter.maydell@linaro.org> Looks reasonable although I don't have a way of testing it on my system. Any idea what systems have the latest sphinx 3 on them? I tried fedora but that still has 1.8.4 so it's not that bleeding edge. Reviewed-by: Alex Bennée <alex.bennee@linaro.org> -- Alex Bennée
On Tue, 14 Apr 2020 at 16:54, Alex Bennée <alex.bennee@linaro.org> wrote: > Looks reasonable although I don't have a way of testing it on my system. > Any idea what systems have the latest sphinx 3 on them? I tried fedora > but that still has 1.8.4 so it's not that bleeding edge. I tested using a sphinx 3 install in a python virtualenv: cd python3 -m venv python-env . ~/python-env/bin/activate pip install sphinx deactivate and then tell configure to use ~/python-env/bin/sphinx-build (or don't deactivate, and then that will be the first sphinx-build on the PATH.) thanks -- PMM
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__] cmd += [filename] try: diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 8dc30e01e58..030b5c8691f 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -71,6 +71,8 @@ Output selection (mutually exclusive): DOC: sections. May be specified multiple times. Output selection modifiers: + -sphinx-version VER Generate rST syntax for the specified Sphinx version. + Only works with reStructuredTextFormat. -no-doc-sections Do not output DOC: sections. -enable-lineno Enable output of #define LINENO lines. Only works with reStructuredText format. @@ -286,6 +288,7 @@ use constant { }; my $output_selection = OUTPUT_ALL; my $show_not_found = 0; # No longer used +my $sphinx_version = "0.0"; # if not specified, assume old my @export_file_list; @@ -436,6 +439,8 @@ while ($ARGV[0] =~ m/^--?(.*)/) { $enable_lineno = 1; } elsif ($cmd eq 'show-not-found') { $show_not_found = 1; # A no-op but don't fail + } elsif ($cmd eq 'sphinx-version') { + $sphinx_version = shift @ARGV; } else { # Unknown argument usage(); @@ -963,7 +968,16 @@ sub output_struct_rst(%) { my $oldprefix = $lineprefix; my $name = $args{'type'} . " " . $args{'struct'}; - print "\n\n.. c:type:: " . $name . "\n\n"; + # Sphinx 3.0 and up will emit warnings for "c:type:: struct Foo". + # It wants to see "c:struct:: Foo" (and will add the word 'struct' in + # the rendered output). + if ((split(/\./, $sphinx_version))[0] >= 3) { + my $sname = $name; + $sname =~ s/^struct //; + print "\n\n.. c:struct:: " . $sname . "\n\n"; + } else { + print "\n\n.. c:type:: " . $name . "\n\n"; + } print_lineno($declaration_start_line); $lineprefix = " "; output_highlight_rst($args{'purpose'});
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 <peter.maydell@linaro.org> --- docs/sphinx/kerneldoc.py | 1 + scripts/kernel-doc | 16 +++++++++++++++- 2 files changed, 16 insertions(+), 1 deletion(-) -- 2.20.1