lkml.org 
[lkml]   [2020]   [Oct]   [13]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
    Patch in this message
    /
    From
    Subject[PATCH v6 02/80] scripts: kernel-doc: make it more compatible with Sphinx 3.x
    Date
    With Sphinx 3.x, the ".. c:type:" tag was changed to accept either:

    .. c:type:: typedef-like declaration
    .. c:type:: name

    Using it for other types (including functions) don't work anymore.

    So, there are newer tags for macro, enum, struct, union, and others,
    which doesn't exist on older versions.

    Add a check for the Sphinx version and change the produced tags
    accordingly.

    Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
    ---
    scripts/kernel-doc | 71 ++++++++++++++++++++++++++++++++++++++++++----
    1 file changed, 65 insertions(+), 6 deletions(-)

    diff --git a/scripts/kernel-doc b/scripts/kernel-doc
    index adc05406c68e..096317ef2e97 100755
    --- a/scripts/kernel-doc
    +++ b/scripts/kernel-doc
    @@ -271,6 +271,8 @@ if ($#ARGV == -1) {
    }

    my $kernelversion;
    +my $sphinx_major;
    +
    my $dohighlight = "";

    my $verbose = 0;
    @@ -465,6 +467,43 @@ while ($ARGV[0] =~ m/^--?(.*)/) {

    # continue execution near EOF;

    +# The C domain dialect changed on Sphinx 3. So, we need to check the
    +# version in order to produce the right tags.
    +sub findprog($)
    +{
    + foreach(split(/:/, $ENV{PATH})) {
    + return "$_/$_[0]" if(-x "$_/$_[0]");
    + }
    +}
    +
    +sub get_sphinx_version()
    +{
    + my $ver;
    + my $major = 1;
    +
    + my $cmd = "sphinx-build";
    + if (!findprog($cmd)) {
    + my $cmd = "sphinx-build3";
    + return $major if (!findprog($cmd));
    + }
    +
    + open IN, "$cmd --version 2>&1 |";
    + while (<IN>) {
    + if (m/^\s*sphinx-build\s+([\d]+)\.([\d\.]+)(\+\/[\da-f]+)?$/) {
    + $major=$1;
    + last;
    + }
    + # Sphinx 1.2.x uses a different format
    + if (m/^\s*Sphinx.*\s+([\d]+)\.([\d\.]+)$/) {
    + $major=$1;
    + last;
    + }
    + }
    + close IN;
    +
    + return $major;
    +}
    +
    # get kernel version from env
    sub get_kernel_version() {
    my $version = 'unknown kernel version';
    @@ -848,7 +887,11 @@ sub output_function_rst(%) {
    my $start = "";

    if ($args{'typedef'}) {
    - print ".. c:type:: ". $args{'function'} . "\n\n";
    + if ($sphinx_major < 3) {
    + print ".. c:type:: ". $args{'function'} . "\n\n";
    + } else {
    + print ".. c:function:: ". $args{'function'} . "\n\n";
    + }
    print_lineno($declaration_start_line);
    print " **Typedef**: ";
    $lineprefix = "";
    @@ -938,9 +981,14 @@ sub output_enum_rst(%) {
    my ($parameter);
    my $oldprefix = $lineprefix;
    my $count;
    - my $name = "enum " . $args{'enum'};

    - print "\n\n.. c:type:: " . $name . "\n\n";
    + if ($sphinx_major < 3) {
    + my $name = "enum " . $args{'enum'};
    + print "\n\n.. c:type:: " . $name . "\n\n";
    + } else {
    + my $name = $args{'enum'};
    + print "\n\n.. c:enum:: " . $name . "\n\n";
    + }
    print_lineno($declaration_start_line);
    $lineprefix = " ";
    output_highlight_rst($args{'purpose'});
    @@ -966,8 +1014,13 @@ sub output_typedef_rst(%) {
    my %args = %{$_[0]};
    my ($parameter);
    my $oldprefix = $lineprefix;
    - my $name = "typedef " . $args{'typedef'};
    + my $name;

    + if ($sphinx_major < 3) {
    + $name = "typedef " . $args{'typedef'};
    + } else {
    + $name = $args{'typedef'};
    + }
    print "\n\n.. c:type:: " . $name . "\n\n";
    print_lineno($declaration_start_line);
    $lineprefix = " ";
    @@ -982,9 +1035,14 @@ sub output_struct_rst(%) {
    my %args = %{$_[0]};
    my ($parameter);
    my $oldprefix = $lineprefix;
    - my $name = $args{'type'} . " " . $args{'struct'};

    - print "\n\n.. c:type:: " . $name . "\n\n";
    + if ($sphinx_major < 3) {
    + my $name = $args{'type'} . " " . $args{'struct'};
    + print "\n\n.. c:type:: " . $name . "\n\n";
    + } else {
    + my $name = $args{'struct'};
    + print "\n\n.. c:struct:: " . $name . "\n\n";
    + }
    print_lineno($declaration_start_line);
    $lineprefix = " ";
    output_highlight_rst($args{'purpose'});
    @@ -2242,6 +2300,7 @@ sub process_file($) {
    }


    +$sphinx_major = get_sphinx_version();
    $kernelversion = get_kernel_version();

    # generate a sequence of code that will splice in highlighting information
    --
    2.26.2
    \
     
     \ /
      Last update: 2020-10-13 13:55    [W:4.071 / U:0.120 seconds]
    ©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site