Re: [PATCH] scripts: kernel-doc: allow passing desired Sphinx C domain dialect

[Jonathan Corbet]

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...

Thanks,

jon