Re: [Qemu-devel] Introducing GSoC project: API Documentation Generation

[Eduardo Habkost]

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 <address@hidden> -----

Date: Thu, 5 Jan 2017 17:47:30 +0100
From: Paolo Bonzini <address@hidden>
To: Peter Maydell <address@hidden>, QEMU Developers <address@hidden>
Cc: Stefan Hajnoczi <address@hidden>
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 "address@hidden"
>    . "&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 = '\&amp;(enum\s*([_\w]+))';
-my $type_struct_xml = '\&amp;(struct\s*([_\w]+))';
-my $type_typedef_xml = '\&amp;(typedef\s*([_\w]+))';
-my $type_union_xml = '\&amp;(union\s*([_\w]+))';
-my $type_member_xml = '\&amp;([_\w]+)(\.|-\&gt;)([_\w]+)';
-my $type_fallback_xml = '\&amp([_\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