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

[Peter Maydell]

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