On Tue, May 21, 2019 at 12:55:36PM +0200, Paolo Bonzini wrote: > On 21/05/19 10:53, Daniel P. Berrangé wrote: > > Hawkmoth seems pretty attractive in its output format, but doesn't appear > > to be part of either Debian or Fedora distros, so we would have to bundle > > it in QEMU I expect. My big concern there is that there have only been > > 2 contributors to Hawkmoth in its entire 3 year existance, which makes > > me fear for its long term viability if the main author gives up. > > On the plus side, I think the main author is among the people that > pushed rST and Sphinx in the kernel, so it's plausible that in the > future the kernel will pick Hawkmoth. I agree that we should check with > him about his plans. > > > QEMU should pick a tool which is well established / widely used & thus > > stands a good chance of being maintained for the long term, as we don't > > want to end up relying on abandonware in 5 years time. The kernel-doc > > project is not widely used, but its main user is significant enough that > > it isn't likely to die through lack of maintainers. > > A couple years ago I didn't have problems modifying kerneldoc for QEMU's > syntax, it was a 10 lines patch. Unfortunately I cannot find it anymore.
Do you mean the following patch? ----- Forwarded message from Paolo Bonzini <pbonz...@redhat.com> ----- Date: Thu, 5 Jan 2017 17:47:30 +0100 From: Paolo Bonzini <pbonz...@redhat.com> To: Peter Maydell <peter.mayd...@linaro.org>, QEMU Developers <qemu-devel@nongnu.org> Cc: Stefan Hajnoczi <stefa...@redhat.com> Subject: Re: [Qemu-devel] Sphinx for QEMU docs? (and a doc-comment format question) On 07/11/2016 16:03, Peter Maydell wrote: > 2) some of the doc-comment format differences are irritating: > . "function - short description" not "function: short description" > . "&struct.fieldname" not ".@fieldname" > . "&typename" not "#typename" > 3) the most awkward part of kernel-doc syntax is that it bakes > in the kernel's style choice of always using "struct foo" > for types -- I don't think there's any way to document > 'MemoryRegion' and 'AddressSpace' without the 'struct' > coming out in the documentation output. > > We could fix (2) by loosening the kernel-doc script's > parsing if we were happy to carry around a forked version > of it. Fixing (3) requires more serious surgery on kernel-doc > I suspect. I've sent some changes to kernel-doc to simplify the implementation of these changes (http://www.spinics.net/lists/linux-doc/msg42354.html) and they were accepted. So with 4.10 + those patches, the local changes to kernel-doc for QEMU would be limited to the following: diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 4c9ada36fe6b..c43ac038398d 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -215,18 +215,18 @@ my $type_func = '(\w+)\(\)'; my $type_param = '\@(\w+(\.\.\.)?)'; my $type_fp_param = '\@(\w+)\(\)'; # Special RST handling for func ptr params my $type_env = '(\$\w+)'; -my $type_enum = '\&(enum\s*([_\w]+))'; -my $type_struct = '\&(struct\s*([_\w]+))'; -my $type_typedef = '\&(typedef\s*([_\w]+))'; -my $type_union = '\&(union\s*([_\w]+))'; -my $type_member = '\&([_\w]+)(\.|->)([_\w]+)'; -my $type_fallback = '\&([_\w]+)'; -my $type_enum_xml = '\&(enum\s*([_\w]+))'; -my $type_struct_xml = '\&(struct\s*([_\w]+))'; -my $type_typedef_xml = '\&(typedef\s*([_\w]+))'; -my $type_union_xml = '\&(union\s*([_\w]+))'; -my $type_member_xml = '\&([_\w]+)(\.|-\>)([_\w]+)'; -my $type_fallback_xml = '\&([_\w]+)'; +my $type_enum = '#(enum\s*([_\w]+))'; +my $type_struct = '#(struct\s*([_\w]+))'; +my $type_typedef = '#(([A-Z][_\w]*))'; +my $type_union = '#(union\s*([_\w]+))'; +my $type_member = '#([_\w]+)(\.|->)([_\w]+)'; +my $type_fallback = '(?!)'; # this never matches +my $type_enum_xml = $type_enum; +my $type_struct_xml = $type_struct; +my $type_typedef_xml = $type_typedef; +my $type_union_xml = $type_union; +my $type_member_xml = $type_member; +my $type_fallback_xml = $type_fallback; my $type_member_func = $type_member . '\(\)'; # Output conversion substitutions. @@ -2143,6 +2143,14 @@ sub output_blockhead { sub dump_declaration($$) { no strict 'refs'; my ($prototype, $file) = @_; + if ($decl_type eq 'type name') { + if ($prototype =~ /^(enum|struct|union)\s+/) { + $decl_type = $1; + } else { + return; + } + } + my $func = "dump_" . $decl_type; &$func(@_); } @@ -2893,7 +2901,7 @@ sub process_file($) { } elsif (/$doc_decl/o) { $identifier = $1; - if (/\s*([\w\s]+?)\s*-/) { + if (/\s*([\w\s]+?)(\s*-|:)/) { $identifier = $1; } @@ -2903,7 +2911,7 @@ sub process_file($) { $contents = ""; $section = $section_default; $new_start_line = $. + 1; - if (/-(.*)/) { + if (/[-:](.*)/) { # strip leading/trailing/multiple spaces $descr= $1; $descr =~ s/^\s*//; @@ -2921,7 +2929,9 @@ sub process_file($) { ++$warnings; } - if ($identifier =~ m/^struct/) { + if ($identifier =~ m/^[A-Z]/) { + $decl_type = 'type name'; + } elsif ($identifier =~ m/^struct/) { $decl_type = 'struct'; } elsif ($identifier =~ m/^union/) { $decl_type = 'union'; which should be maintainable as a fork of Linux's kernel-doc. I also worked a bit on support for Texinfo manuals in Sphinx. My current attempt is at http://people.redhat.com/pbonzini/qemu-test-doc/_build/. Because this uses a Texinfo->Docbook->Sphinx pipeline, I also tried some tools with native Docbook support (Publican), but despite Sphinx's quirks the output was less usable, and the tools were slower and harder to use. http://wiki.qemu-project.org/Features/Documentation is another place to brainstorm ideas on this. Paolo ----- End forwarded message ----- -- Eduardo
