[RFC PATCH 00/29] kernel-doc: update from Linux 5.10

Paolo Bonzini posted 29 patches 3 years, 4 months ago
Test checkpatch passed
Patches applied successfully (tree, apply log)
git fetch https://github.com/patchew-project/qemu tags/patchew/20201117165312.118257-1-pbonzini@redhat.com
Maintainers: Peter Maydell <peter.maydell@linaro.org>
There is a newer version of this series
docs/sphinx/kerneldoc.py |   1 -
scripts/kernel-doc       | 453 +++++++++++++++++++++++++++------------
2 files changed, 318 insertions(+), 136 deletions(-)
[RFC PATCH 00/29] kernel-doc: update from Linux 5.10
Posted by Paolo Bonzini 3 years, 4 months ago
This series updates kernel-doc to Linux 5.10, which removes the need for
all of our downstream patches (except for the syntax changes, of course).
Sphinx 3 works, as do the QOM typedefs that needed QEMU-specific changes.
All the patches apply cleanly.

Paolo

Alexander A. Klimov (1):
  Replace HTTP links with HTTPS ones: documentation

André Almeida (2):
  kernel-doc: fix processing nested structs with attributes
  kernel-doc: add support for ____cacheline_aligned_in_smp attribute

Jonathan Cameron (1):
  kernel-doc: add support for ____cacheline_aligned attribute

Jonathan Neuschäfer (1):
  scripts/kernel-doc: Add support for named variable macro arguments

Mauro Carvalho Chehab (19):
  scripts: kernel-doc: proper handle @foo->bar()
  scripts: kernel-doc: accept negation like !@var
  scripts: kernel-doc: accept blank lines on parameter description
  scripts/kernel-doc: parse __ETHTOOL_DECLARE_LINK_MODE_MASK
  scripts/kernel-doc: handle function pointer prototypes
  kernel-doc: include line numbers for function prototypes
  scripts: kernel-doc: add support for typedef enum
  scripts: kernel-doc: make it more compatible with Sphinx 3.x
  scripts: kernel-doc: use a less pedantic markup for funcs on Sphinx
    3.x
  scripts: kernel-doc: fix troubles with line counts
  scripts: kernel-doc: reimplement -nofunction argument
  scripts: kernel-doc: fix typedef identification
  scripts: kernel-doc: don't mangle with parameter list
  scripts: kernel-doc: allow passing desired Sphinx C domain dialect
  scripts: kernel-doc: fix line number handling
  scripts: kernel-doc: try to use c:function if possible
  scripts: kernel-doc: fix typedef parsing
  scripts: kernel-doc: split typedef complex regex
  scripts: kernel-doc: use :c:union when needed

Paolo Bonzini (4):
  Revert "scripts/kerneldoc: For Sphinx 3 use c:macro for macros with
    arguments"
  Revert "kernel-doc: Use c:struct for Sphinx 3.0 and later"
  Revert "kernel-doc: Handle function typedefs without asterisks"
  Revert "kernel-doc: Handle function typedefs that return pointers"

Pierre-Louis Bossart (1):
  scripts/kernel-doc: optionally treat warnings as errors

 docs/sphinx/kerneldoc.py |   1 -
 scripts/kernel-doc       | 453 +++++++++++++++++++++++++++------------
 2 files changed, 318 insertions(+), 136 deletions(-)

-- 
2.28.0


Re: [RFC PATCH 00/29] kernel-doc: update from Linux 5.10
Posted by Peter Maydell 3 years, 4 months ago
On Tue, 17 Nov 2020 at 16:54, Paolo Bonzini <pbonzini@redhat.com> wrote:
>
> This series updates kernel-doc to Linux 5.10, which removes the need for
> all of our downstream patches (except for the syntax changes, of course).
> Sphinx 3 works, as do the QOM typedefs that needed QEMU-specific changes.
> All the patches apply cleanly.

This seems like a good way to update kernel-doc without the revision
history and/or the commits looking like a confusing mess. I note that
it will break bisection of the documentation builds for systems with
a Sphinx 3, though.

If we wanted to completely make the series bisection safe we could add
a patch at the start that simply comments out the five kernel-doc
directives in docs/devel/*.rst, and then have a final patch at the
end that reverts it. That seems like it would be simple enough and
it would avoid anybody doing a bisection run on a newer host having
to remember to put --disable-docs in their configure arguments.

>   scripts: kernel-doc: allow passing desired Sphinx C domain dialect

Your port of this kernel commit is missing the hunk which
must be applied to our docs/sphinx/kerneldoc.py:

--- a/Documentation/sphinx/kerneldoc.py
+++ b/Documentation/sphinx/kerneldoc.py
@@ -70,6 +70,11 @@ class KernelDocDirective(Directive):
         env = self.state.document.settings.env
         cmd = [env.config.kerneldoc_bin, '-rst', '-enable-lineno']

+       # Pass the version string to kernel-doc, as it needs to use a different
+       # dialect, depending what the C domain supports for each specific
+       # Sphinx versions
+        cmd += ['-sphinx-version', sphinx.__version__]
+
         filename = env.config.kerneldoc_srctree + '/' + self.arguments[0]
         export_file_patterns = []

Without that the docs do not build on Sphinx 3.2.

More generally it would probably be reasonable to sync also
kerneldoc.py -- we're only slightly adrift of the kernel version
and we don't need any of the changes the kernel has, but syncing
it at the same time we sync kernel-doc is probably less confusing.

I did a diff of the final kernel-doc against the kernel version.
Mostly the diff looks like changes we want (and it's pretty small,
which is great). This hunk, however:

@@ -1758,7 +1758,7 @@
     # If you mess with these regexps, it's a good idea to check that
     # the following functions' documentation still comes out right:
     # - parport_register_device (function pointer parameters)
-    # - atomic_set (macro)
+    # - qatomic_set (macro)
     # - pci_match_device, __copy_to_user (long return type)

is an unintentional change from QEMU commit d73415a31547, which
did a global search-and-replace of a function name.
We should probably add a patch to this series to
revert it, so we stay as close to the kernel's copy of the
script as possible.

I tested this patchset with builds using sphinx 1.6,
2.0, 2.4, 3.0 and 3.2; other than the kerneldoc.py change
mentioned above there were no problems.

thanks
-- PMM

Re: [RFC PATCH 00/29] kernel-doc: update from Linux 5.10
Posted by Paolo Bonzini 3 years, 4 months ago
On 30/11/20 12:28, Peter Maydell wrote:
> If we wanted to completely make the series bisection safe we could add
> a patch at the start that simply comments out the five kernel-doc
> directives in docs/devel/*.rst, and then have a final patch at the
> end that reverts it. That seems like it would be simple enough and
> it would avoid anybody doing a bisection run on a newer host having
> to remember to put --disable-docs in their configure arguments.
> 
>>    scripts: kernel-doc: allow passing desired Sphinx C domain dialect
> 
> Your port of this kernel commit is missing the hunk which
> must be applied to our docs/sphinx/kerneldoc.py:
> 
> More generally it would probably be reasonable to sync also
> kerneldoc.py -- we're only slightly adrift of the kernel version
> and we don't need any of the changes the kernel has, but syncing
> it at the same time we sync kernel-doc is probably less confusing.
> 
> I did a diff of the final kernel-doc against the kernel version.
> Mostly the diff looks like changes we want (and it's pretty small,
> which is great). This hunk, however:
> 
> @@ -1758,7 +1758,7 @@
>       # If you mess with these regexps, it's a good idea to check that
>       # the following functions' documentation still comes out right:
>       # - parport_register_device (function pointer parameters)
> -    # - atomic_set (macro)
> +    # - qatomic_set (macro)
>       # - pci_match_device, __copy_to_user (long return type)
> 
> is an unintentional change from QEMU commit d73415a31547, which
> did a global search-and-replace of a function name.
> We should probably add a patch to this series to
> revert it, so we stay as close to the kernel's copy of the
> script as possible.

Ok, I'll clean these up and resend.

Paolo