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

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <20201005101736.7adf4f46@lwn.net>
Date:   Mon, 5 Oct 2020 10:17:36 -0600
From:   Jonathan Corbet <corbet@....net>
To:     Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
Cc:     Linux Doc Mailing List <linux-doc@...r.kernel.org>,
        Changbin Du <changbin.du@...el.com>,
        linux-kernel@...r.kernel.org
Subject: Re: [PATCH] scripts: kernel-doc: allow passing desired Sphinx C
 domain dialect

On Sun,  4 Oct 2020 10:02:03 +0200
Mauro Carvalho Chehab <mchehab+huawei@...nel.org> 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@....net>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
> ---
>  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