On Tue, 17 Nov 2020 at 16:54, Paolo Bonzini <pbonz...@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
