[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [Qemu-devel] Introducing GSoC project: API Documentation Generation
From: |
Paolo Bonzini |
Subject: |
Re: [Qemu-devel] Introducing GSoC project: API Documentation Generation |
Date: |
Tue, 21 May 2019 19:14:29 +0200 |
User-agent: |
Mozilla/5.0 (X11; Linux x86_64; rv:60.0) Gecko/20100101 Thunderbird/60.6.1 |
On 21/05/19 18:17, Eduardo Habkost wrote:
> 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?
You're awesome! :)
Paolo
> ----- 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 = '\&(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.
- Re: [Qemu-devel] Introducing GSoC project: API Documentation Generation, (continued)
- Re: [Qemu-devel] Introducing GSoC project: API Documentation Generation, Peter Maydell, 2019/05/21
- Re: [Qemu-devel] Introducing GSoC project: API Documentation Generation, Paolo Bonzini, 2019/05/21
- Re: [Qemu-devel] Introducing GSoC project: API Documentation Generation, John Snow, 2019/05/21
- Re: [Qemu-devel] Introducing GSoC project: API Documentation Generation, Eduardo Habkost, 2019/05/21
- Re: [Qemu-devel] Introducing GSoC project: API Documentation Generation, Paolo Bonzini, 2019/05/22
- Re: [Qemu-devel] Introducing GSoC project: API Documentation Generation, John Snow, 2019/05/23
- Re: [Qemu-devel] Introducing GSoC project: API Documentation Generation, Paolo Bonzini, 2019/05/24
- Re: [Qemu-devel] Introducing GSoC project: API Documentation Generation, Eduardo Habkost, 2019/05/24
- Re: [Qemu-devel] Introducing GSoC project: API Documentation Generation, Paolo Bonzini, 2019/05/24
- Re: [Qemu-devel] Introducing GSoC project: API Documentation Generation, Eduardo Habkost, 2019/05/21
- Re: [Qemu-devel] Introducing GSoC project: API Documentation Generation,
Paolo Bonzini <=
Re: [Qemu-devel] Introducing GSoC project: API Documentation Generation, Peter Maydell, 2019/05/21