Em Mon, 5 Oct 2020 10:17:36 -0600
Jonathan Corbet <corbet@xxxxxxx> escreveu:
> On Sun, 4 Oct 2020 10:02:03 +0200
> Mauro Carvalho Chehab <mchehab+huawei@xxxxxxxxxx> wrote:
>
> > When kernel-doc is called via kerneldoc.py, there's no need to
> > auto-detect the Sphinx version, as the Sphinx module already
> > knows it. So, add an optional parameter to allow changing the
> > Sphinx dialect.
> >
> > As kernel-doc can also be manually called, keep the auto-detection
> > logic if the parameter was not specified. On such case, emit
> > a warning if sphinx-build can't be found at PATH.
> >
> > Suggested-by: Jonathan Corbet <corbet@xxxxxxx>
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@xxxxxxxxxx>
> > ---
> > Documentation/sphinx/kerneldoc.py | 5 ++++
> > scripts/kernel-doc | 40 ++++++++++++++++++++++++-------
> > 2 files changed, 37 insertions(+), 8 deletions(-)
>
> So I'm glad to see this. Still not fully sold on the autodetection, but if
> we don't actually use it, maybe I can live with it :)
>
> One little nit:
>
> > diff --git a/Documentation/sphinx/kerneldoc.py b/Documentation/sphinx/kerneldoc.py
> > index 233f610539f0..e9857ab904f1 100644
> > --- a/Documentation/sphinx/kerneldoc.py
> > +++ b/Documentation/sphinx/kerneldoc.py
> > + } elsif ($cmd eq "sphinx-version") {
> > + my $ver_string = shift @ARGV;
> > + if ($ver_string =~ m/^(\d+)\.(\d+)\.(\d+)/) {
> > + $sphinx_major = $1;
> > + $sphinx_minor = $2;
> > + $sphinx_patch = $3;
> > + } else {
> > + die "Sphinx version should be at major.minor.patch format\n";
> > + }
>
> Can we allow just major.minor, with patch defaulting to zero? People
> passing this by hand may not want to look up their patch version every
> time, and I doubt it will ever matter...
Sure. It should be easy to make the third argument optional, although
the regex will be a little more harder to understand.
Something like this should do the trick:
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 01efb0afb8c2..104d79949a8a 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -466,12 +466,16 @@ while ($ARGV[0] =~ m/^--?(.*)/) {
$show_not_found = 1; # A no-op but don't fail
} elsif ($cmd eq "sphinx-version") {
my $ver_string = shift @ARGV;
- if ($ver_string =~ m/^(\d+)\.(\d+)\.(\d+)/) {
+ if ($ver_string =~ m/^(\d+)\.(\d+)(?:\.?(\d+)?)/) {
$sphinx_major = $1;
$sphinx_minor = $2;
- $sphinx_patch = $3;
+ if ($3) {
+ $sphinx_patch = $3;
+ } else {
+ $sphinx_patch = 0;
+ }
} else {
- die "Sphinx version should be at major.minor.patch format\n";
+ die "Sphinx version should either major.minor or major.minor.patch format\n";
}
} else {
# Unknown argument
As right now we don't support Sphinx version 3.0[1], we're actually using just
$sphinx_major. So, I'm wonder if it would make sense to also make <minor>
optional.
The change would be trivial, although the regex will become even more
harder to read ;-)
[1] not sure how valuable would be adding support for Sphinx 3.0. While
I didn't make any tests, I'm strongly suspecting that, with the approach
we took for backward/forward compatibility, adding support for it
would mean to just do a trivial change at cdomain.py by applying a
patch that Markus did replacing a regex function that doesn't exist
anymore at Sphinx API and emulating C namespace with the logic I
already implemented.
I guess I'll give it a try anyway, as it seems weird to have a gap
in the middle of the supported versions.
Thanks,
Mauro
