Add documentation for Documentation/features at the built docs
Subsystems (6)
cover Add documentation for Documentation/features at the built docs
Hi Jon,
This series got already submitted last year:
https://lore.kernel.org/lkml/[email protected]/
Yet, on that time, there were too many other patches related to ReST conversion floating around. So, at the end, I guess this one got missed.
So, I did a rebase on the top of upstream, and added a few new changes.
Patch 1 contains the original implementation back then. It adds a get_feat.pl script that parses the contents of Documentation/features.
Patch 2 is new: it re-implements the output of the full contents of the features table as a set of per-subsystem tables.
Patch 3 replaces the existing Documentation/features/list-arch.sh by a call to the new script, in order to avoid having two scripts doing the same thing.
Patch 4 is a sphinx extension to allow generating features output via a meta-tag.
Patch 5 adds a complete feature list covering all archs at the admin guide.
Patch 6 adds a per-arch feature list on each architecture book.
-
The scripts/get_feat.pl supports several types of output:
- $ scripts/get_feat.pl current
Outputs the supported feadures by the architecture of the running Kernel, as an ASCII table;
- $ scripts/get_feat.pl list
Outputs the supported features on an easy to be parsed format. By default, it uses the current architecture as well;
- $ scripts/get_feat.pl rest --feature jump-labels
Output what architecture supports a given feature (on the above example, "jump-labels" feature)
- $ scripts/get_feat.pl rest --arch um
Outputs the features support for an specific architecture (on the above example, for "um" architecture.
- $ scripts/get_feat.pl rest
Outputs a text file with ASCII tables (ReST compatible) with all features, grouped per subsystem.
E. g. something like:
================= Feature status on all architectures
=================
Subsystem: core
=======
+---------------------+---------------------------------+-------------------------------------------------------------------------+------------+------+
|Feature |Kconfig |Description |Architecture|Status|
+===========+=================+=====================================+======+===+
|cBPF-JIT |HAVE_CBPF_JIT |arch supports cBPF JIT optimizations |alpha |TODO |
| | | +------------+------+
| | | |arc |TODO |
| | | +------------+------+
| | | |arm |TODO |
| | | +------------+------+
| | | |arm64 |TODO |
| | | +------------+------+
| | | |c6x |TODO |
| | | +------------+------+
| | | |csky |TODO |
| | | +------------+------+
| | | |h8300 |TODO |
| | | +------------+------+
| | | |hexagon |TODO |
...
Adding those patchsets will basically place the contents of all files under Documentation/features (currently, 45 files) at the Kernel documentation, which is, IMO, a good thing to do.
Regards,
Mauro
Mauro Carvalho Chehab (6):
scripts: get_feat.pl: add a script to handle Documentation/features
scripts: get_feat.pl: improve matrix output
scripts: get_feat.pl: use its implementation for list-arch.sh
sphinx: kernel_feat.py: add a script to parse feature files
docs: admin-guide: add a features list
docs: archis: add a per-architecture features list
Documentation/admin-guide/features.rst | 3 + Documentation/admin-guide/index.rst | 1 + Documentation/arm/features.rst | 3 + Documentation/arm/index.rst | 2 + Documentation/arm64/features.rst | 3 + Documentation/arm64/index.rst | 2 + Documentation/conf.py | 2 +- Documentation/features/list-arch.sh | 17 +- Documentation/ia64/features.rst | 3 + Documentation/ia64/index.rst | 2 + Documentation/index.rst | 2 +- Documentation/m68k/features.rst | 3 + Documentation/m68k/index.rst | 2 + Documentation/mips/features.rst | 3 + Documentation/mips/index.rst | 2 + Documentation/nios2/index.rst | 12 + Documentation/openrisc/features.rst | 3 + Documentation/openrisc/index.rst | 2 + Documentation/parisc/features.rst | 3 + Documentation/parisc/index.rst | 2 + Documentation/powerpc/features.rst | 3 + Documentation/powerpc/index.rst | 2 + Documentation/riscv/features.rst | 3 + Documentation/riscv/index.rst | 2 + Documentation/s390/features.rst | 3 + Documentation/s390/index.rst | 2 + Documentation/sh/features.rst | 3 + Documentation/sh/index.rst | 2 + Documentation/sparc/features.rst | 3 + Documentation/sparc/index.rst | 2 + Documentation/sphinx/kernel_feat.py | 169 ++++++++ Documentation/x86/features.rst | 3 + Documentation/x86/index.rst | 1 + Documentation/xtensa/features.rst | 3 + Documentation/xtensa/index.rst | 2 + scripts/get_feat.pl | 552 +++++++++++++++++++++++++ 36 files changed, 810 insertions(+), 17 deletions(-) create mode 100644 Documentation/admin-guide/features.rst create mode 100644 Documentation/arm/features.rst create mode 100644 Documentation/arm64/features.rst create mode 100644 Documentation/ia64/features.rst create mode 100644 Documentation/m68k/features.rst create mode 100644 Documentation/mips/features.rst create mode 100644 Documentation/nios2/index.rst create mode 100644 Documentation/openrisc/features.rst create mode 100644 Documentation/parisc/features.rst create mode 100644 Documentation/powerpc/features.rst create mode 100644 Documentation/riscv/features.rst create mode 100644 Documentation/s390/features.rst create mode 100644 Documentation/sh/features.rst create mode 100644 Documentation/sparc/features.rst create mode 100644 Documentation/sphinx/kernel_feat.py create mode 100644 Documentation/x86/features.rst create mode 100644 Documentation/xtensa/features.rst create mode 100755 scripts/get_feat.pl
Signature · 1 line
2.28.0
PATCH 1/6 scripts: get_feat.pl: add a script to handle Documentation/features
The Documentation/features contains a set of parseable files. It is not worth converting them to ReST format, as they're useful the way it is. It is, however, interesting to parse them and produce output on different formats:
1) Output the contents of a feature in ReST format;
2) Output what features a given architecture supports;
3) Output a matrix with features x architectures.
--- scripts/get_feat.pl | 474 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 474 insertions(+) create mode 100755 scripts/get_feat.pl
scripts/get_feat.pl new file +474 -0
@@ -0,0 +1,474 @@ +#!/usr/bin/perl +# SPDX-License-Identifier: GPL-2.0 + +use strict; +use Pod::Usage; +use Getopt::Long; +use File::Find; +use Fcntl ':mode'; + +my $help; +my $man; +my $debug; +my $arch; +my $feat; +my $prefix="Documentation/features"; + +GetOptions( + "debug|d+" => \$debug, + "dir=s" => \$prefix, + 'help|?' => \$help, + 'arch=s' => \$arch, + 'feat=s' => \$feat, + man => \$man +) or pod2usage(2); + +pod2usage(1) if $help; +pod2usage(-exitstatus => 0, -verbose => 2) if $man; + +pod2usage(2) if (scalar @ARGV < 1 || @ARGV > 2); + +my ($cmd, $arg) = @ARGV; + +pod2usage(2) if ($cmd ne "current" && $cmd ne "rest" && $cmd ne "validate"); + +require Data::Dumper if ($debug); + +my %data; +my %archs; + +# +# Displays an error message, printing file name and line +# +sub parse_error($$$$) { + my ($file, $ln, $msg, $data) = @_; + + $data =~ s/\s+$/\n/; + + print STDERR "Warning: file $file#$ln:\n\t$msg"; + + if ($data ne "") { + print STDERR ". Line\n\t\t$data"; + } else { + print STDERR "\n"; + } +} + +# +# Parse a features file, storing its contents at %data +# + +my $h_name = "Feature"; +my $h_kconfig = "Kconfig"; +my $h_description = "Description"; +my $h_subsys = "Subsystem"; +my $h_status = "Status"; +my $h_arch = "Architecture"; + +my $max_size_name = length($h_name); +my $max_size_kconfig = length($h_kconfig); +my $max_size_description = length($h_description); +my $max_size_subsys = length($h_subsys); +my $max_size_status = length($h_status); +my $max_size_arch = length($h_arch); + +sub parse_feat { + my $file = $File::Find::name; + + my $mode = (stat($file))[2]; + return if ($mode & S_IFDIR); + return if ($file =~ m,($prefix)/arch-support.txt,); + return if (!($file =~ m,arch-support.txt$,)); + + my $subsys = ""; + $subsys = $2 if ( m,.*($prefix)/([^/]+).*,); + + if (length($subsys) > $max_size_subsys) { + $max_size_subsys = length($subsys); + } + + my $name; + my $kconfig; + my $description; + my $comments = ""; + my $last_status; + my $ln; + my %arch_table; + + print STDERR "Opening $file\n" if ($debug > 1); + open IN, $file; + + while(<IN>) { + $ln++; + + if (m/^\#\s+Feature\s+name:\s*(.*\S)/) { + $name = $1; + if (length($name) > $max_size_name) { + $max_size_name = length($name); + } + next; + } + if (m/^\#\s+Kconfig:\s*(.*\S)/) { + $kconfig = $1; + if (length($kconfig) > $max_size_kconfig) { + $max_size_kconfig = length($kconfig); + } + next; + } + if (m/^\#\s+description:\s*(.*\S)/) { + $description = $1; + if (length($description) > $max_size_description) { + $max_size_description = length($description); + } + next; + } + next if (m/^\\s*$/); + next if (m/^\s*\-+\s*$/); + next if (m/^\s*\|\s*arch\s*\|\s*status\s*\|\s*$/); + + if (m/^\#\s*(.*)/) { + $comments .= "$1\n"; + next; + } + if (m/^\s*\|\s*(\S+):\s*\|\s*(\S+)\s*\|\s*$/) { + my $a = $1; + my $status = $2; + + if (length($status) > $max_size_status) { + $max_size_status = length($status); + } + if (length($a) > $max_size_arch) { + $max_size_arch = length($a); + } + + $status = "---" if ($status =~ m/^\.\.$/); + + $archs{$a} = 1; + $arch_table{$a} = $status; + next; + } + + #Everything else is an error + parse_error($file, $ln, "line is invalid", $_); + } + close IN; + + if (!$name) { + parse_error($file, $ln, "Feature name not found", ""); + return; + } + + parse_error($file, $ln, "Subsystem not found", "") if (!$subsys); + parse_error($file, $ln, "Kconfig not found", "") if (!$kconfig); + parse_error($file, $ln, "Description not found", "") if (!$description); + + if (!%arch_table) { + parse_error($file, $ln, "Architecture table not found", ""); + return; + } + + $data{$name}->{where} = $file; + $data{$name}->{subsys} = $subsys; + $data{$name}->{kconfig} = $kconfig; + $data{$name}->{description} = $description; + $data{$name}->{comments} = $comments; + $data{$name}->{table} = \%arch_table; +} + +# +# Output feature(s) for a given architecture +# +sub output_arch_table { + my $title = "Feature status on $arch architecture"; + + print "=" x length($title) . "\n"; + print "$title\n"; + print "=" x length($title) . "\n\n"; + + print "=" x $max_size_subsys; + print " "; + print "=" x $max_size_name; + print " "; + print "=" x $max_size_kconfig; + print " "; + print "=" x $max_size_status; + print " "; + print "=" x $max_size_description; + print "\n"; + printf "%-${max_size_subsys}s ", $h_subsys; + printf "%-${max_size_name}s ", $h_name; + printf "%-${max_size_kconfig}s ", $h_kconfig; + printf "%-${max_size_status}s ", $h_status; + printf "%-${max_size_description}s\n", $h_description; + print "=" x $max_size_subsys; + print " "; + print "=" x $max_size_name; + print " "; + print "=" x $max_size_kconfig; + print " "; + print "=" x $max_size_status; + print " "; + print "=" x $max_size_description; + print "\n"; + + foreach my $name (sort { + ($data{$a}->{subsys} cmp $data{$b}->{subsys}) || + ($data{$a}->{name} cmp $data{$b}->{name}) + } keys %data) { + next if ($feat && $name ne $feat); + + my %arch_table = %{$data{$name}->{table}}; + printf "%-${max_size_subsys}s ", $data{$name}->{subsys}; + printf "%-${max_size_name}s ", $name; + printf "%-${max_size_kconfig}s ", $data{$name}->{kconfig}; + printf "%-${max_size_status}s ", $arch_table{$arch}; + printf "%-${max_size_description}s\n", $data{$name}->{description}; + } + + print "=" x $max_size_subsys; + print " "; + print "=" x $max_size_name; + print " "; + print "=" x $max_size_kconfig; + print " "; + print "=" x $max_size_status; + print " "; + print "=" x $max_size_description; + print "\n"; +} + +# +# Output a feature on all architectures +# +sub output_feature { + my $title = "Feature $feat"; + + print "=" x length($title) . "\n"; + print "$title\n"; + print "=" x length($title) . "\n\n"; + + print ":Subsystem: $data{$feat}->{subsys} \n" if ($data{$feat}->{subsys}); + print ":Kconfig: $data{$feat}->{kconfig} \n" if ($data{$feat}->{kconfig}); + + my $desc = $data{$feat}->{description}; + $desc =~ s/^([a-z])/\U$1/; + $desc =~ s/\.?\s*//; + print "\n$desc.\n\n"; + + my $com = $data{$feat}->{comments}; + $com =~ s/^\s+//; + $com =~ s/\s+$//; + if ($com) { + print "Comments\n"; + print "--------\n\n"; + print "$com\n\n"; + } + + print "=" x $max_size_arch; + print " "; + print "=" x $max_size_status; + print "\n"; + + printf "%-${max_size_arch}s ", $h_arch; + printf "%-${max_size_status}s", $h_status . "\n"; + + print "=" x $max_size_arch; + print " "; + print "=" x $max_size_status; + print "\n"; + + my %arch_table = %{$data{$feat}->{table}}; + foreach my $arch (sort keys %arch_table) { + printf "%-${max_size_arch}s ", $arch; + printf "%-${max_size_status}s\n", $arch_table{$arch}; + } + + print "=" x $max_size_arch; + print " "; + print "=" x $max_size_status; + print "\n"; +} + +# +# Output all features for all architectures +# + +sub matrix_lines { + print "=" x $max_size_subsys; + print " "; + print "=" x $max_size_name; + print " "; + + foreach my $arch (sort keys %archs) { + my $len = $max_size_status; + + $len = length($arch) if ($len < length($arch)); + + print "=" x $len; + print " "; + } + print "=" x $max_size_kconfig; + print " "; + print "=" x $max_size_description; + print "\n"; +} + +sub output_matrix { + + my $title = "Feature List (feature x architecture)"; + + print "=" x length($title) . "\n"; + print "$title\n"; + print "=" x length($title) . "\n\n"; + + matrix_lines; + + printf "%-${max_size_subsys}s ", $h_subsys; + printf "%-${max_size_name}s ", $h_name; + + foreach my $arch (sort keys %archs) { + printf "%-${max_size_status}s ", $arch; + } + printf "%-${max_size_kconfig}s ", $h_kconfig; + printf "%-${max_size_description}s\n", $h_description; + + matrix_lines; + + foreach my $name (sort { + ($data{$a}->{subsys} cmp $data{$b}->{subsys}) || + ($data{$a}->{name} cmp $data{$b}->{name}) + } keys %data) { + printf "%-${max_size_subsys}s ", $data{$name}->{subsys}; + printf "%-${max_size_name}s ", $name; + + my %arch_table = %{$data{$name}->{table}}; + + foreach my $arch (sort keys %arch_table) { + my $len = $max_size_status; + + $len = length($arch) if ($len < length($arch)); + + printf "%-${len}s ", $arch_table{$arch}; + } + printf "%-${max_size_kconfig}s ", $data{$name}->{kconfig}; + printf "%-${max_size_description}s\n", $data{$name}->{description}; + } + + matrix_lines; +} + + +# +# Parses all feature files located at $prefix dir +# +find({wanted =>\&parse_feat, no_chdir => 1}, $prefix); + +print STDERR Data::Dumper->Dump([\%data], [qw(*data)]) if ($debug); + +# +# Handles the command +# +if ($cmd eq "current") { + $arch = qx(uname -m | sed 's/x86_64/x86/' | sed 's/i386/x86/'); + $arch =~s/\s+$//; +} + +if ($cmd ne "validate") { + if ($arch) { + output_arch_table; + } elsif ($feat) { + output_feature; + } else { + output_matrix; + } +} + +__END__ + +=head1 NAME + +get_feat.pl - parse the Linux Feature files and produce a ReST book. + +=head1 SYNOPSIS + +B<get_feat.pl> [--debug] [--man] [--help] [--dir=<dir>] + [--arch=<arch>] [--feat=<feature>] <COMAND> [<ARGUMENT>] + +Where <COMMAND> can be: + +=over 8 + +B<current> - output features for this machine's architecture + +B<rest> - output features in ReST markup language + +B<validate> - validate the feature contents + +=back + +=head1 OPTIONS + +=over 8 + +=item B<--arch> + +Output features for an specific architecture, optionally filtering for +a single specific feature. + +=item B<--feat> + +Output features for a single specific architecture. + +=item B<--dir> + +Changes the location of the Feature files. By default, it uses +the Documentation/features directory. + +=item B<--debug> + +Put the script in verbose mode, useful for debugging. Can be called multiple +times, to increase verbosity. + +=item B<--help> + +Prints a brief help message and exits. + +=item B<--man> + +Prints the manual page and exits. + +=back + +=head1 DESCRIPTION + +Parse the Linux feature files from Documentation/features (by default), +optionally producing results at ReST format. + +It supports output data per architecture, per feature or a +feature x arch matrix. + +When used with B<rest> command, it will use either one of the tree formats: + +If neither B<--arch> or B<--feature> arguments are used, it will output a +matrix with features per architecture. + +If B<--arch> argument is used, it will output the features availability for +a given architecture. + +If B<--feat> argument is used, it will output the content of the feature +file using ReStructured Text markup. + +=head1 BUGS + +Report bugs to Mauro Carvalho Chehab <[email protected]> + +=head1 COPYRIGHT + +Copyright (c) 2019 by Mauro Carvalho Chehab <[email protected]>. + +License GPLv2: GNU GPL version 2 <http://gnu.org/licenses/gpl.html>. + +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law. + +=cut
Signature · 1 line
2.28.0
PATCH 2/6 scripts: get_feat.pl: improve matrix output
In reply to Mauro Carvalho ChehabInstead of producing a too wide table, let's split it per subsystem, and use a better notation in order to make easier for the reader to identify how a feature is supported on multiple architectures.
--- scripts/get_feat.pl | 113 +++++++++++++++++++++++++++----------------- 1 file changed, 70 insertions(+), 43 deletions(-)
scripts/get_feat.pl +70 -43
@@ -293,68 +293,95 @@ sub output_feature { # Output all features for all architectures # -sub matrix_lines { - print "=" x $max_size_subsys; - print " "; - print "=" x $max_size_name; - print " "; +sub matrix_lines($$) { + my $partial = shift; + my $header = shift; + my $split; + my $fill; + my $ln_marker; - foreach my $arch (sort keys %archs) { - my $len = $max_size_status; - - $len = length($arch) if ($len < length($arch)); + if ($header) { + $ln_marker = "="; + } else { + $ln_marker = "-"; + } - print "=" x $len; - print " "; + if ($partial) { + $split = "|"; + $fill = " "; + } else { + $split = "+"; + $fill = $ln_marker; } - print "=" x $max_size_kconfig; - print " "; - print "=" x $max_size_description; - print "\n"; + + print $split; + print $fill x $max_size_name; + print $split; + print $fill x $max_size_kconfig; + print $split; + print $fill x $max_size_description; + print "+"; + print $ln_marker x $max_size_arch; + print "+"; + print $ln_marker x $max_size_status; + print "+\n"; } sub output_matrix { - - my $title = "Feature List (feature x architecture)"; + my $title = "Feature status on all architectures"; print "=" x length($title) . "\n"; print "$title\n"; print "=" x length($title) . "\n\n"; - matrix_lines; - - printf "%-${max_size_subsys}s ", $h_subsys; - printf "%-${max_size_name}s ", $h_name; - - foreach my $arch (sort keys %archs) { - printf "%-${max_size_status}s ", $arch; - } - printf "%-${max_size_kconfig}s ", $h_kconfig; - printf "%-${max_size_description}s\n", $h_description; - - matrix_lines; - + my $cur_subsys = ""; foreach my $name (sort { - ($data{$a}->{subsys} cmp $data{$b}->{subsys}) || - ($data{$a}->{name} cmp $data{$b}->{name}) + ($data{$a}->{subsys} cmp $data{$b}->{subsys}) or + ($a cmp $b) } keys %data) { - printf "%-${max_size_subsys}s ", $data{$name}->{subsys}; - printf "%-${max_size_name}s ", $name; + + if ($cur_subsys ne $data{$name}->{subsys}) { + if ($cur_subsys ne "") { + printf "\n"; + } + + $cur_subsys = $data{$name}->{subsys}; + + my $title = "Subsystem: $cur_subsys"; + print "$title\n"; + print "=" x length($title) . "\n\n"; + + matrix_lines(0, 0); + printf "|%-${max_size_name}s", $h_name; + printf "|%-${max_size_kconfig}s", $h_kconfig; + printf "|%-${max_size_description}s", $h_description; + + printf "|%-${max_size_arch}s", $h_arch; + printf "|%-${max_size_status}s|\n", $h_status; + + matrix_lines(0, 1); + } my %arch_table = %{$data{$name}->{table}}; - + my $first = 1; foreach my $arch (sort keys %arch_table) { - my $len = $max_size_status; + if ($first) { + printf "|%-${max_size_name}s", $name; + printf "|%-${max_size_kconfig}s", $data{$name}->{kconfig}; + printf "|%-${max_size_description}s", $data{$name}->{description}; + $first = 0; + } else { + matrix_lines(1, 0); - $len = length($arch) if ($len < length($arch)); - - printf "%-${len}s ", $arch_table{$arch}; + printf "|%-${max_size_name}s", ""; + printf "|%-${max_size_kconfig}s", ""; + printf "|%-${max_size_description}s", ""; + } + printf "|%-${max_size_arch}s", $arch; + printf "|%-${max_size_status}s|\n", $arch_table{$arch}; } - printf "%-${max_size_kconfig}s ", $data{$name}->{kconfig}; - printf "%-${max_size_description}s\n", $data{$name}->{description}; + matrix_lines(0, 0); } - - matrix_lines; }
Signature · 1 line
2.28.0
PATCH 3/6 scripts: get_feat.pl: use its implementation for list-arch.sh
In reply to Mauro Carvalho ChehabAdd support for the same output format as the bash script, and use its implementation instead of the previous one.
I opted to do such patch in order to have a single script responsible for parsing Documentation/features and produce different outputs.
As someone may rely on the past format, which is easy to parse it, get_feat.pl now gains a new command with the same output format as the previous script.
As a side effect, the perl script is a lot faster, as it reads each file only once, instead of parsing files several times via a for command and grep commands inside it.
This patch also changes the features list order to be case-insensitive, in order to better match the output of the existing script.
--- Documentation/features/list-arch.sh | 17 +------ scripts/get_feat.pl | 77 ++++++++++++++++++++++++----- 2 files changed, 66 insertions(+), 28 deletions(-)
Documentation/features/list-arch.sh +2 -15
@@ -1,3 +1,4 @@ +# SPDX-License-Identifier: GPL-2.0 # # Small script that visualizes the kernel feature support status # of an architecture.
@@ -7,18 +8,4 @@ ARCH=${1:-$(uname -m | sed 's/x86_64/x86/' | sed 's/i386/x86/')} -cd $(dirname $0) -echo "#" -echo "# Kernel feature support matrix of the '$ARCH' architecture:" -echo "#" - -for F in */*/arch-support.txt; do - SUBSYS=$(echo $F | cut -d/ -f1) - N=$(grep -h "^# Feature name:" $F | cut -c25-) - C=$(grep -h "^# Kconfig:" $F | cut -c25-) - D=$(grep -h "^# description:" $F | cut -c25-) - S=$(grep -hv "^#" $F | grep -w $ARCH | cut -d\| -f3) - - printf "%10s/%-22s:%s| %35s # %s\n" "$SUBSYS" "$N" "$S" "$C" "$D" -done - +$(dirname $0)/../../scripts/get_feat.pl list --arch $ARCH
scripts/get_feat.pl +64 -13
154 lines not on this page · raw message
Signature · 1 line
2.28.0
PATCH 4/6 sphinx: kernel_feat.py: add a script to parse feature files
In reply to Mauro Carvalho ChehabThe feature files have a special well-defined format. Add a script that parses them, allowing to search for a feature and/or by an architecture and to produce ReST-compatible outputs.
--- Documentation/sphinx/kernel_feat.py | 169 ++++++++++++++++++++++++++++ 1 file changed, 169 insertions(+) create mode 100644 Documentation/sphinx/kernel_feat.py
Documentation/sphinx/kernel_feat.py new file +169 -0
@@ -0,0 +1,169 @@ +# coding=utf-8 +# SPDX-License-Identifier: GPL-2.0 +# +u""" + kernel-feat + ~~~~~~~~~~~ + + Implementation of the ``kernel-feat`` reST-directive. + + :copyright: Copyright (C) 2016 Markus Heiser + :copyright: Copyright (C) 2016-2019 Mauro Carvalho Chehab + :maintained-by: Mauro Carvalho Chehab <[email protected]> + :license: GPL Version 2, June 1991 see Linux/COPYING for details. + + The ``kernel-feat`` (:py:class:`KernelFeat`) directive calls the + scripts/get_feat.pl script to parse the Kernel ABI files. + + Overview of directive's argument and options. + + .. code-block:: rst + + .. kernel-feat:: <ABI directory location> + :debug: + + The argument ``<ABI directory location>`` is required. It contains the + location of the ABI files to be parsed. + + ``debug`` + Inserts a code-block with the *raw* reST. Sometimes it is helpful to see + what reST is generated. + +""" + +import codecs +import os +import subprocess +import sys + +from os import path + +from docutils import nodes, statemachine +from docutils.statemachine import ViewList +from docutils.parsers.rst import directives, Directive +from docutils.utils.error_reporting import ErrorString + +# +# AutodocReporter is only good up to Sphinx 1.7 +# +import sphinx + +Use_SSI = sphinx.__version__[:3] >= '1.7' +if Use_SSI: + from sphinx.util.docutils import switch_source_input +else: + from sphinx.ext.autodoc import AutodocReporter + +__version__ = '1.0' + +def setup(app): + + app.add_directive("kernel-feat", KernelFeat) + return dict( + version = __version__ + , parallel_read_safe = True + , parallel_write_safe = True + ) + +class KernelFeat(Directive): + + u"""KernelFeat (``kernel-feat``) directive""" + + required_arguments = 1 + optional_arguments = 2 + has_content = False + final_argument_whitespace = True + + option_spec = { + "debug" : directives.flag + } + + def warn(self, message, **replace): + replace["fname"] = self.state.document.current_source + replace["line_no"] = replace.get("line_no", self.lineno) + message = ("%(fname)s:%(line_no)s: [kernel-feat WARN] : " + message) % replace + self.state.document.settings.env.app.warn(message, prefix="") + + def run(self): + + doc = self.state.document + if not doc.settings.file_insertion_enabled: + raise self.warning("docutils: file insertion disabled") + + env = doc.settings.env + cwd = path.dirname(doc.current_source) + cmd = "get_feat.pl rest --dir " + cmd += self.arguments[0] + + if len(self.arguments) > 1: + cmd += " --arch " + self.arguments[1] + + srctree = path.abspath(os.environ["srctree"]) + + fname = cmd + + # extend PATH with $(srctree)/scripts + path_env = os.pathsep.join([ + srctree + os.sep + "scripts", + os.environ["PATH"] + ]) + shell_env = os.environ.copy() + shell_env["PATH"] = path_env + shell_env["srctree"] = srctree + + lines = self.runCmd(cmd, shell=True, cwd=cwd, env=shell_env) + nodeList = self.nestedParse(lines, fname) + return nodeList + + def runCmd(self, cmd, **kwargs): + u"""Run command ``cmd`` and return it's stdout as unicode.""" + + try: + proc = subprocess.Popen( + cmd + , stdout = subprocess.PIPE + , stderr = subprocess.PIPE + , **kwargs + ) + out, err = proc.communicate() + + out, err = codecs.decode(out, 'utf-8'), codecs.decode(err, 'utf-8') + + if proc.returncode != 0: + raise self.severe( + u"command '%s' failed with return code %d" + % (cmd, proc.returncode) + ) + except OSError as exc: + raise self.severe(u"problems with '%s' directive: %s." + % (self.name, ErrorString(exc))) + return out + + def nestedParse(self, lines, fname): + content = ViewList() + node = nodes.section() + + if "debug" in self.options: + code_block = "\n\n.. code-block:: rst\n :linenos:\n" + for l in lines.split("\n"): + code_block += "\n " + l + lines = code_block + "\n\n" + + for c, l in enumerate(lines.split("\n")): + content.append(l, fname, c) + + buf = self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter + + if Use_SSI: + with switch_source_input(self.state, content): + self.state.nested_parse(content, 0, node, match_titles=1) + else: + self.state.memo.title_styles = [] + self.state.memo.section_level = 0 + self.state.memo.reporter = AutodocReporter(content, self.state.memo.reporter) + try: + self.state.nested_parse(content, 0, node, match_titles=1) + finally: + self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter = buf + + return node.children
Signature · 1 line
2.28.0
PATCH 5/6 docs: admin-guide: add a features list
In reply to Mauro Carvalho ChehabAdd a feature list matrix at the admin-guide.
--- Documentation/admin-guide/features.rst | 3 +++ Documentation/admin-guide/index.rst | 1 + Documentation/conf.py | 2 +- 3 files changed, 5 insertions(+), 1 deletion(-) create mode 100644 Documentation/admin-guide/features.rst
Documentation/admin-guide/features.rst new file +3 -0
@@ -0,0 +1,3 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. kernel-feat:: $srctree/Documentation/features
Documentation/admin-guide/index.rst +1 -0
@@ -19,6 +19,7 @@ etc. sysctl/index abi + features This section describes CPU vulnerabilities and their mitigations.
Documentation/conf.py +1 -1
@@ -39,7 +39,7 @@ needs_sphinx = '1.3' extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include', 'kfigure', 'sphinx.ext.ifconfig', 'automarkup', 'maintainers_include', 'sphinx.ext.autosectionlabel', - 'kernel_abi'] + 'kernel_abi', 'kernel_feat'] # # cdomain is badly broken in Sphinx 3+. Leaving it out generates *most*
Signature · 1 line
2.28.0
PATCH 6/6 docs: archis: add a per-architecture features list
In reply to Mauro Carvalho ChehabAdd a feature list matrix for each architecture to their respective Kernel books.
--- Documentation/arm/features.rst | 3 +++ Documentation/arm/index.rst | 2 ++ Documentation/arm64/features.rst | 3 +++ Documentation/arm64/index.rst | 2 ++ Documentation/ia64/features.rst | 3 +++ Documentation/ia64/index.rst | 2 ++ Documentation/index.rst | 2 +- Documentation/m68k/features.rst | 3 +++ Documentation/m68k/index.rst | 2 ++ Documentation/mips/features.rst | 3 +++ Documentation/mips/index.rst | 2 ++ Documentation/nios2/index.rst | 12 ++++++++++++ Documentation/openrisc/features.rst | 3 +++ Documentation/openrisc/index.rst | 2 ++ Documentation/parisc/features.rst | 3 +++ Documentation/parisc/index.rst | 2 ++ Documentation/powerpc/features.rst | 3 +++ Documentation/powerpc/index.rst | 2 ++ Documentation/riscv/features.rst | 3 +++ Documentation/riscv/index.rst | 2 ++ Documentation/s390/features.rst | 3 +++ Documentation/s390/index.rst | 2 ++ Documentation/sh/features.rst | 3 +++ Documentation/sh/index.rst | 2 ++ Documentation/sparc/features.rst | 3 +++ Documentation/sparc/index.rst | 2 ++ Documentation/x86/features.rst | 3 +++ Documentation/x86/index.rst | 1 + Documentation/xtensa/features.rst | 3 +++ Documentation/xtensa/index.rst | 2 ++ 30 files changed, 82 insertions(+), 1 deletion(-) create mode 100644 Documentation/arm/features.rst create mode 100644 Documentation/arm64/features.rst create mode 100644 Documentation/ia64/features.rst create mode 100644 Documentation/m68k/features.rst create mode 100644 Documentation/mips/features.rst create mode 100644 Documentation/nios2/index.rst create mode 100644 Documentation/openrisc/features.rst create mode 100644 Documentation/parisc/features.rst create mode 100644 Documentation/powerpc/features.rst create mode 100644 Documentation/riscv/features.rst create mode 100644 Documentation/s390/features.rst create mode 100644 Documentation/sh/features.rst create mode 100644 Documentation/sparc/features.rst create mode 100644 Documentation/x86/features.rst create mode 100644 Documentation/xtensa/features.rst
Documentation/arm/features.rst new file +3 -0
@@ -0,0 +1,3 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. kernel-feat:: $srctree/Documentation/features arm
Documentation/arm/index.rst +2 -0
@@ -23,6 +23,8 @@ ARM Architecture vlocks porting + features + SoC-specific documents ===========
Documentation/arm64/features.rst new file +3 -0
@@ -0,0 +1,3 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. kernel-feat:: $srctree/Documentation/features arm64
Documentation/arm64/index.rst +2 -0
@@ -24,6 +24,8 @@ ARM64 Architecture tagged-address-abi tagged-pointers + features + .. only:: subproject and html Indices
Documentation/ia64/features.rst new file +3 -0
@@ -0,0 +1,3 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. kernel-feat:: $srctree/Documentation/features ia64
Documentation/ia64/index.rst +2 -0
@@ -15,3 +15,5 @@ IA-64 Architecture irq-redir mca serial + + features
Documentation/index.rst +1 -1
@@ -160,7 +160,7 @@ implementation. ia64/index m68k/index mips/index - nios2/nios2 + nios2/index openrisc/index parisc/index powerpc/index
Documentation/m68k/features.rst new file +3 -0
@@ -0,0 +1,3 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. kernel-feat:: $srctree/Documentation/features m68k
Documentation/m68k/index.rst +2 -0
@@ -10,6 +10,8 @@ m68k Architecture kernel-options buddha-driver + features + .. only:: subproject and html Indices
Documentation/mips/features.rst new file +3 -0
@@ -0,0 +1,3 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. kernel-feat:: $srctree/Documentation/features mips
Documentation/mips/index.rst +2 -0
@@ -11,6 +11,8 @@ MIPS-specific Documentation booting ingenic-tcu + features + .. only:: subproject and html Indices
Documentation/nios2/index.rst new file +12 -0
@@ -0,0 +1,12 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=============== +Nios II Specific Documentation +=============== + +.. toctree:: + :maxdepth: 2 + :numbered: + + nios2 + features
Documentation/openrisc/features.rst new file +3 -0
@@ -0,0 +1,3 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. kernel-feat:: $srctree/Documentation/features openrisc
Documentation/openrisc/index.rst +2 -0
@@ -10,6 +10,8 @@ OpenRISC Architecture openrisc_port todo + features + .. only:: subproject and html Indices
Documentation/parisc/features.rst new file +3 -0
@@ -0,0 +1,3 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. kernel-feat:: $srctree/Documentation/features parisc
Documentation/parisc/index.rst +2 -0
@@ -10,6 +10,8 @@ PA-RISC Architecture debugging registers + features + .. only:: subproject and html Indices
Documentation/powerpc/features.rst new file +3 -0
@@ -0,0 +1,3 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. kernel-feat:: $srctree/Documentation/features powerpc
Documentation/powerpc/index.rst +2 -0
@@ -34,6 +34,8 @@ powerpc vas-api vcpudispatch_stats + features + .. only:: subproject and html Indices
Documentation/riscv/features.rst new file +3 -0
@@ -0,0 +1,3 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. kernel-feat:: $srctree/Documentation/features riscv
Documentation/riscv/index.rst +2 -0
@@ -9,6 +9,8 @@ RISC-V architecture pmu patch-acceptance + features + .. only:: subproject and html Indices
Documentation/s390/features.rst new file +3 -0
@@ -0,0 +1,3 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. kernel-feat:: $srctree/Documentation/features s390
Documentation/s390/index.rst +2 -0
@@ -19,6 +19,8 @@ s390 Architecture text_files + features + .. only:: subproject and html Indices
Documentation/sh/features.rst new file +3 -0
@@ -0,0 +1,3 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. kernel-feat:: $srctree/Documentation/features sh
Documentation/sh/index.rst +2 -0
@@ -11,6 +11,8 @@ SuperH Interfaces Guide new-machine register-banks + features + Memory Management ========
Documentation/sparc/features.rst new file +3 -0
@@ -0,0 +1,3 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. kernel-feat:: $srctree/Documentation/features sparc
Documentation/sparc/index.rst +2 -0
@@ -9,3 +9,5 @@ Sparc Architecture adi oradax/oracle-dax + + features
Documentation/x86/features.rst new file +3 -0
@@ -0,0 +1,3 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. kernel-feat:: $srctree/Documentation/features x86
Documentation/x86/index.rst +1 -0
@@ -33,3 +33,4 @@ x86-specific Documentation i386/index x86_64/index sva + features
Documentation/xtensa/features.rst new file +3 -0
@@ -0,0 +1,3 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. kernel-feat:: $srctree/Documentation/features xtensa
Documentation/xtensa/index.rst +2 -0
@@ -10,3 +10,5 @@ Xtensa Architecture atomctl booting mmu + + features
Signature · 1 line
2.28.0
Jonathan Corbet
maintainerQuoted 8 lines · On Mon, 30 Nov 2020 16:36:29 +0100 Mauro Carvalho Chehab…
This series got already submitted last year:
https://lore.kernel.org/lkml/[email protected]/Yet, on that time, there were too many other patches related to ReST conversion floating around. So, at the end, I guess this one got missed.
So, I did a rebase on the top of upstream, and added a few new changes.
OK, I've gone ahead and applied these; it gains me a new trivial conflict with x86, but so be it...
That said, I think that the RST table formatting could be *way* improved. The current tables are all white space and hard to make sense of. What if we condensed the information? Just looking at the first entry in Documentation/admin-guide/features.html, perhaps it could look like:
FEATURE KCONFIG/DESCRIPTION STATUS
cBPF-JIT HAVE_CBPF_JIT TODO: alpha, arc, arm...
ok: mips, powerpc, ...
arch supports cBPF JIT
optimizations
The result would be far more compact and easy to read, IMO. I may get around to giving this a try if (hint :) nobody else gets there first.
Thanks,
jon
PATCH 1/1 scripts: get_feat.pl: make complete table more coincise
Currently, there are too many white spaces at the tables, and the information is very sparsed on it.
Make the format a lot more compact.
--- scripts/get_feat.pl | 107 +++++++++++++++++++++++++++++++++----------- 1 file changed, 81 insertions(+), 26 deletions(-)
scripts/get_feat.pl +81 -26
@@ -325,7 +325,9 @@ sub output_feature { # Output all features for all architectures # -sub matrix_lines($$) { +sub matrix_lines($$$$) { + my $desc_size = shift; + my $status_size = shift; my $partial = shift; my $header = shift; my $split;
@@ -349,13 +351,9 @@ sub matrix_lines($$) { print $split; print $fill x $max_size_name; print $split; - print $fill x $max_size_kconfig; - print $split; - print $fill x $max_size_description; + print $fill x $desc_size; print "+"; - print $ln_marker x $max_size_arch; - print "+"; - print $ln_marker x $max_size_status; + print $ln_marker x $status_size; print "+\n"; }
@@ -366,6 +364,14 @@ sub output_matrix { print "$title\n"; print "=" x length($title) . "\n\n"; + my $desc_title = "$h_kconfig / $h_description"; + + my $desc_size = $max_size_kconfig + 4; + $desc_size = $max_size_description if ($max_size_description > $desc_size); + $desc_size = length($desc_title) if (length($desc_title) > $desc_size); + + my $status_size = 60; + my $cur_subsys = ""; foreach my $name (sort { ($data{$a}->{subsys} cmp $data{$b}->{subsys}) or
@@ -383,36 +389,85 @@ sub output_matrix { print "$title\n"; print "=" x length($title) . "\n\n"; - matrix_lines(0, 0); + + matrix_lines($desc_size, $status_size, 0, 0); + printf "|%-${max_size_name}s", $h_name; - printf "|%-${max_size_kconfig}s", $h_kconfig; - printf "|%-${max_size_description}s", $h_description; + printf "|%-${desc_size}s", $desc_title; - printf "|%-${max_size_arch}s", $h_arch; - printf "|%-${max_size_status}s|\n", $h_status; - - matrix_lines(0, 1); + printf "|%-${status_size}s|\n", "Status per architecture"; + matrix_lines($desc_size, $status_size, 0, 1); } my %arch_table = %{$data{$name}->{table}}; - my $first = 1; - foreach my $arch (sort keys %arch_table) { - if ($first) { + my $cur_status = ""; + + my @lines; + my $line = ""; + foreach my $arch (sort { + ($arch_table{$a} cmp $arch_table{$b}) or + ("\L$a" cmp "\L$b") + } keys %arch_table) { + + my $status = $arch_table{$arch}; + + if ($status eq "---") { + $status = "Not compatible"; + } + + if ($status ne $cur_status) { + if ($line ne "") { + push @lines, $line; + $line = ""; + } + $line = "- **" . $status . "**: " . $arch; + } elsif (length($line) + length ($arch) + 2 < $status_size) { + $line .= ", " . $arch; + } else { + push @lines, $line; + $line = " " . $arch; + } + $cur_status = $status; + } + push @lines, $line if ($line ne ""); + + my $ln = 0; + for my $line(@lines) { + if (!$ln) { printf "|%-${max_size_name}s", $name; - printf "|%-${max_size_kconfig}s", $data{$name}->{kconfig}; - printf "|%-${max_size_description}s", $data{$name}->{description}; - $first = 0; + printf "|%-${desc_size}s", "``" . $data{$name}->{kconfig} . "``"; + } elsif ($ln == 2) { + printf "|%-${max_size_name}s", ""; + printf "|%-${desc_size}s", $data{$name}->{description}; } else { - matrix_lines(1, 0); + printf "|%-${max_size_name}s", ""; + printf "|%-${desc_size}s", ""; + } + + printf "|%-${status_size}s|\n", $line; + $ln++; + } + + # Ensure that Kconfig and description will be printed + while ($ln < 2) { + if (!$ln) { + printf "|%-${max_size_name}s", $name; + printf "|%-${desc_size}s``", $data{$name}->{kconfig} . "``"; + } elsif ($ln == 2) { printf "|%-${max_size_name}s", ""; - printf "|%-${max_size_kconfig}s", ""; - printf "|%-${max_size_description}s", ""; + printf "|%-${desc_size}s", $data{$name}->{description}; + } else { + printf "|%-${max_size_name}s", ""; + printf "|%-${desc_size}s", ""; } - printf "|%-${max_size_arch}s", $arch; - printf "|%-${max_size_status}s|\n", $arch_table{$arch}; + + printf "|%-${status_size}s|\n", ""; + + $ln++; } - matrix_lines(0, 0); + + matrix_lines($desc_size, $status_size, 0, 0); } }
Signature · 1 line
2.28.0
PATCH v2 1/1 scripts: get_feat.pl: make complete table more coincise
Currently, there are too many white spaces at the tables, and the information is very sparsed on it.
Make the format a lot more compact.
--- scripts/get_feat.pl | 119 ++++++++++++++++++++++++++++++-------------- 1 file changed, 83 insertions(+), 36 deletions(-)
scripts/get_feat.pl +83 -36
@@ -325,10 +325,10 @@ sub output_feature { # Output all features for all architectures # -sub matrix_lines($$) { - my $partial = shift; +sub matrix_lines($$$) { + my $desc_size = shift; + my $status_size = shift; my $header = shift; - my $split; my $fill; my $ln_marker;
@@ -338,24 +338,14 @@ sub matrix_lines($$) { $ln_marker = "-"; } - if ($partial) { - $split = "|"; - $fill = " "; - } else { - $split = "+"; - $fill = $ln_marker; - } + $fill = $ln_marker; - print $split; + print "+"; print $fill x $max_size_name; - print $split; - print $fill x $max_size_kconfig; - print $split; - print $fill x $max_size_description; print "+"; - print $ln_marker x $max_size_arch; + print $fill x $desc_size; print "+"; - print $ln_marker x $max_size_status; + print $ln_marker x $status_size; print "+\n"; }
@@ -366,6 +356,14 @@ sub output_matrix { print "$title\n"; print "=" x length($title) . "\n\n"; + my $desc_title = "$h_kconfig / $h_description"; + + my $desc_size = $max_size_kconfig + 4; + $desc_size = $max_size_description if ($max_size_description > $desc_size); + $desc_size = length($desc_title) if (length($desc_title) > $desc_size); + + my $status_size = 60; + my $cur_subsys = ""; foreach my $name (sort { ($data{$a}->{subsys} cmp $data{$b}->{subsys}) or
@@ -383,36 +381,85 @@ sub output_matrix { print "$title\n"; print "=" x length($title) . "\n\n"; - matrix_lines(0, 0); + + matrix_lines($desc_size, $status_size, 0); + printf "|%-${max_size_name}s", $h_name; - printf "|%-${max_size_kconfig}s", $h_kconfig; - printf "|%-${max_size_description}s", $h_description; + printf "|%-${desc_size}s", $desc_title; - printf "|%-${max_size_arch}s", $h_arch; - printf "|%-${max_size_status}s|\n", $h_status; - - matrix_lines(0, 1); + printf "|%-${status_size}s|\n", "Status per architecture"; + matrix_lines($desc_size, $status_size, 1); } my %arch_table = %{$data{$name}->{table}}; - my $first = 1; - foreach my $arch (sort keys %arch_table) { - if ($first) { + my $cur_status = ""; + + my @lines; + my $line = ""; + foreach my $arch (sort { + ($arch_table{$a} cmp $arch_table{$b}) or + ("\L$a" cmp "\L$b") + } keys %arch_table) { + + my $status = $arch_table{$arch}; + + if ($status eq "---") { + $status = "Not compatible"; + } + + if ($status ne $cur_status) { + if ($line ne "") { + push @lines, $line; + $line = ""; + } + $line = "- **" . $status . "**: " . $arch; + } elsif (length($line) + length ($arch) + 2 < $status_size) { + $line .= ", " . $arch; + } else { + push @lines, $line; + $line = " " . $arch; + } + $cur_status = $status; + } + push @lines, $line if ($line ne ""); + + my $ln = 0; + for my $line(@lines) { + if (!$ln) { printf "|%-${max_size_name}s", $name; - printf "|%-${max_size_kconfig}s", $data{$name}->{kconfig}; - printf "|%-${max_size_description}s", $data{$name}->{description}; - $first = 0; + printf "|%-${desc_size}s", "``" . $data{$name}->{kconfig} . "``"; + } elsif ($ln == 2) { + printf "|%-${max_size_name}s", ""; + printf "|%-${desc_size}s", $data{$name}->{description}; } else { - matrix_lines(1, 0); + printf "|%-${max_size_name}s", ""; + printf "|%-${desc_size}s", ""; + } + + printf "|%-${status_size}s|\n", $line; + $ln++; + } + + # Ensure that Kconfig and description will be printed + while ($ln < 2) { + if (!$ln) { + printf "|%-${max_size_name}s", $name; + printf "|%-${desc_size}s``", $data{$name}->{kconfig} . "``"; + } elsif ($ln == 2) { printf "|%-${max_size_name}s", ""; - printf "|%-${max_size_kconfig}s", ""; - printf "|%-${max_size_description}s", ""; + printf "|%-${desc_size}s", $data{$name}->{description}; + } else { + printf "|%-${max_size_name}s", ""; + printf "|%-${desc_size}s", ""; } - printf "|%-${max_size_arch}s", $arch; - printf "|%-${max_size_status}s|\n", $arch_table{$arch}; + + printf "|%-${status_size}s|\n", ""; + + $ln++; } - matrix_lines(0, 0); + + matrix_lines($desc_size, $status_size, 0); } }
Signature · 1 line
2.28.0
PATCH v3 1/1 scripts: get_feat.pl: make complete table more coincise
Currently, there are too many white spaces at the tables, and the information is very sparsed on it.
Make the format a lot more compact.
---
- v3: cleanup the logic that ensures a minimal number of lines;
- v2: cleanup the matrix_lines function to remove a now unused parameter.
scripts/get_feat.pl | 105 ++++++++++++++++++++++++++++---------------- 1 file changed, 68 insertions(+), 37 deletions(-)
scripts/get_feat.pl +68 -37
@@ -325,10 +325,10 @@ sub output_feature { # Output all features for all architectures # -sub matrix_lines($$) { - my $partial = shift; +sub matrix_lines($$$) { + my $desc_size = shift; + my $status_size = shift; my $header = shift; - my $split; my $fill; my $ln_marker;
@@ -338,24 +338,14 @@ sub matrix_lines($$) { $ln_marker = "-"; } - if ($partial) { - $split = "|"; - $fill = " "; - } else { - $split = "+"; - $fill = $ln_marker; - } + $fill = $ln_marker; - print $split; + print "+"; print $fill x $max_size_name; - print $split; - print $fill x $max_size_kconfig; - print $split; - print $fill x $max_size_description; print "+"; - print $ln_marker x $max_size_arch; + print $fill x $desc_size; print "+"; - print $ln_marker x $max_size_status; + print $ln_marker x $status_size; print "+\n"; }
@@ -366,6 +356,14 @@ sub output_matrix { print "$title\n"; print "=" x length($title) . "\n\n"; + my $desc_title = "$h_kconfig / $h_description"; + + my $desc_size = $max_size_kconfig + 4; + $desc_size = $max_size_description if ($max_size_description > $desc_size); + $desc_size = length($desc_title) if (length($desc_title) > $desc_size); + + my $status_size = 60; + my $cur_subsys = ""; foreach my $name (sort { ($data{$a}->{subsys} cmp $data{$b}->{subsys}) or
@@ -383,36 +381,69 @@ sub output_matrix { print "$title\n"; print "=" x length($title) . "\n\n"; - matrix_lines(0, 0); + + matrix_lines($desc_size, $status_size, 0); + printf "|%-${max_size_name}s", $h_name; - printf "|%-${max_size_kconfig}s", $h_kconfig; - printf "|%-${max_size_description}s", $h_description; + printf "|%-${desc_size}s", $desc_title; - printf "|%-${max_size_arch}s", $h_arch; - printf "|%-${max_size_status}s|\n", $h_status; - - matrix_lines(0, 1); + printf "|%-${status_size}s|\n", "Status per architecture"; + matrix_lines($desc_size, $status_size, 1); } my %arch_table = %{$data{$name}->{table}}; - my $first = 1; - foreach my $arch (sort keys %arch_table) { - if ($first) { + my $cur_status = ""; + + my @lines; + my $line = ""; + foreach my $arch (sort { + ($arch_table{$a} cmp $arch_table{$b}) or + ("\L$a" cmp "\L$b") + } keys %arch_table) { + + my $status = $arch_table{$arch}; + + if ($status eq "---") { + $status = "Not compatible"; + } + + if ($status ne $cur_status) { + if ($line ne "") { + push @lines, $line; + $line = ""; + } + $line = "- **" . $status . "**: " . $arch; + } elsif (length($line) + length ($arch) + 2 < $status_size) { + $line .= ", " . $arch; + } else { + push @lines, $line; + $line = " " . $arch; + } + $cur_status = $status; + } + push @lines, $line if ($line ne ""); + + # Ensure that description will be printed + push @lines, "" while (scalar(@lines) < 2); + + my $ln = 0; + for my $line(@lines) { + if (!$ln) { printf "|%-${max_size_name}s", $name; - printf "|%-${max_size_kconfig}s", $data{$name}->{kconfig}; - printf "|%-${max_size_description}s", $data{$name}->{description}; - $first = 0; + printf "|%-${desc_size}s", "``" . $data{$name}->{kconfig} . "``"; + } elsif ($ln == 2) { + printf "|%-${max_size_name}s", ""; + printf "|%-${desc_size}s", $data{$name}->{description}; } else { - matrix_lines(1, 0); - printf "|%-${max_size_name}s", ""; - printf "|%-${max_size_kconfig}s", ""; - printf "|%-${max_size_description}s", ""; + printf "|%-${desc_size}s", ""; } - printf "|%-${max_size_arch}s", $arch; - printf "|%-${max_size_status}s|\n", $arch_table{$arch}; + + printf "|%-${status_size}s|\n", $line; + + $ln++; } - matrix_lines(0, 0); + matrix_lines($desc_size, $status_size, 0); } }
Signature · 1 line
2.28.0
Re: [PATCH v3] scripts: get_feat.pl: make complete table more coincise
Em Fri, 4 Dec 2020 10:35:44 +0100
Mauro Carvalho Chehab <[email protected]> escreveu:
Quoted 7 lines
Currently, there are too many white spaces at the tables, and the information is very sparsed on it.
Make the format a lot more compact.
Suggested-by Jonathan Corbet <[email protected]>Signed-off-by Mauro Carvalho Chehab <[email protected]>
...
Review
Quoted 6 lines
(quoted diff) +6
-0+ my @lines; + my $line = ""; + foreach my $arch (sort { + ($arch_table{$a} cmp $arch_table{$b}) or + ("\L$a" cmp "\L$b") + } keys %arch_table) {
Actually, I have one doubt myself with the above sort.
Right now, it places things on this order:
Not Compatible: ... TODO: ... ok: ...
I'm wondering if it would it be better to place them at the reverse order, e. g.:
ok: ... TODO: ... Not Compatible: ...
In other words, to output it like:
+---------------------+-------------------------------------------------------------------------+------------------------------------------------------------+ |Feature |Kconfig / Description |Status per architecture | +=====================+=========================================================================+============================================================+ |batch-unmap-tlb-flush|``ARCH_WANT_BATCHED_UNMAP_TLB_FLUSH`` |- **ok**: x86 | | | |- **TODO**: alpha, arc, arm, arm64, csky, hexagon, ia64 | | |arch supports deferral of TLB flush until multiple pages are unmapped | mips, nds32, parisc, powerpc, riscv, s390, sh, sparc | | | | xtensa | | | |- **Not compatible**: c6x, h8300, m68k, microblaze, nios2 | | | | openrisc, um | +---------------------+-------------------------------------------------------------------------+------------------------------------------------------------+ |ELF-ASLR |``ARCH_HAS_ELF_RANDOMIZE`` |- **ok**: arm, arm64, mips, parisc, powerpc, s390, x86 | | | |- **TODO**: alpha, arc, c6x, csky, h8300, hexagon, ia64 | | |arch randomizes the stack, heap and binary images of ELF binaries | m68k, microblaze, nds32, nios2, openrisc, riscv, sh | | | | sparc, um, xtensa | +---------------------+-------------------------------------------------------------------------+------------------------------------------------------------+ |huge-vmap |``HAVE_ARCH_HUGE_VMAP`` |- **ok**: arm64, powerpc, x86 | | | |- **TODO**: alpha, arc, arm, c6x, csky, h8300, hexagon | | |arch supports the ioremap_pud_enabled() and ioremap_pmd_enabled() VM APIs| ia64, m68k, microblaze, mips, nds32, nios2, openrisc | | | | parisc, riscv, s390, sh, sparc, um, xtensa | +---------------------+-------------------------------------------------------------------------+------------------------------------------------------------+ |ioremap_prot |``HAVE_IOREMAP_PROT`` |- **ok**: arc, mips, powerpc, s390, sh, x86 | | | |- **TODO**: alpha, arm, arm64, c6x, csky, h8300, hexagon | | |arch has ioremap_prot() | ia64, m68k, microblaze, nds32, nios2, openrisc, parisc | | | | riscv, sparc, um, xtensa | +---------------------+-------------------------------------------------------------------------+------------------------------------------------------------+ |PG_uncached |``ARCH_USES_PG_UNCACHED`` |- **ok**: ia64, x86 | | | |- **TODO**: alpha, arc, arm, arm64, c6x, csky, h8300 | | |arch supports the PG_uncached page flag | hexagon, m68k, microblaze, mips, nds32, nios2, openrisc | | | | parisc, powerpc, riscv, s390, sh, sparc, um, xtensa | +---------------------+-------------------------------------------------------------------------+------------------------------------------------------------+ |pte_special |``ARCH_HAS_PTE_SPECIAL`` |- **ok**: arc, arm, arm64, mips, powerpc, riscv, s390, sh | | | | sparc, x86 | | |arch supports the pte_special()/pte_mkspecial() VM APIs |- **TODO**: alpha, c6x, csky, h8300, hexagon, ia64, m68k | | | | microblaze, nds32, nios2, openrisc, parisc, um, xtensa | +---------------------+-------------------------------------------------------------------------+------------------------------------------------------------+ |THP |``HAVE_ARCH_TRANSPARENT_HUGEPAGE`` |- **ok**: arc, arm, arm64, mips, powerpc, s390, sparc, x86 | | | |- **TODO**: alpha, ia64, nds32, parisc, riscv | | |arch supports transparent hugepages |- **Not compatible**: c6x, csky, h8300, hexagon, m68k | | | | microblaze, nios2, openrisc, sh, um, xtensa | +---------------------+-------------------------------------------------------------------------+------------------------------------------------------------+
Changing the order is one line patch (see enclosed).
If you think that reverting the order looks better, feel free to apply the enclosed patch, or fold it with the previous one.
Thanks,
Mauro
[PATCH] script: get_feat: change the group by order
Right now, arch compatibility is grouped by status at the alphabetical order from A to Z, and then from a to z, e. g:.
--- TODO ok
Revert the order, in order to print first the OK results, then TODO, and, finally, the not compatible ones.
scripts/get_feat.pl +1 -1
@@ -397,7 +397,7 @@ sub output_matrix { my @lines; my $line = ""; foreach my $arch (sort { - ($arch_table{$a} cmp $arch_table{$b}) or + ($arch_table{$b} cmp $arch_table{$a}) or ("\L$a" cmp "\L$b") } keys %arch_table) {
v4 cover improve get_feat.pl output when all features are displayed
In reply to Jonathan CorbetJon,
As requested, those patches improve the output of the script, when all features are displayed.
The first patch was already posted as-is at v3.
Patch 2 is optional. IMO, it makes more sense for the admin guide to show the architectures where the features are OK, then TODO, and finally the ones that are incompatible with the features. I already sent it together with a comment.
Patch 3 is new: it tries to reduce the width of the table, in order for it to better fit on a terminal. With the patch, the number of columns were reduced, in order to better fit at console output. Before the patch, the output takes 281 lines with 158 columns (total size: 38.9 kB). After the patch, displaying all features require 439 lines and 92 columns (total size: 37.6 kB).
While not implemented, it shold be trivial to allow controlling the number of columns via command line (with a 2 line patch).
I ended dropping such control basically because I was too lazy to add the helper for the two new command line parameters ;-) (and because it probably doesn't matter much sense for the user to control it - I guess).
Mauro Carvalho Chehab (3):
scripts: get_feat.pl: make complete table more coincise
scripts: get_feat.pl: change the group by order
scripts: get_feat.pl: reduce table width for all features output
scripts/get_feat.pl | 160 ++++++++++++++++++++++++++++++++------------ 1 file changed, 119 insertions(+), 41 deletions(-)
Signature · 1 line
2.28.0
PATCH v4 1/3 scripts: get_feat.pl: make complete table more coincise
Currently, there are too many white spaces at the tables, and the information is very sparsed on it.
Make the format a lot more compact.
--- scripts/get_feat.pl | 105 ++++++++++++++++++++++++++++---------------- 1 file changed, 68 insertions(+), 37 deletions(-)
scripts/get_feat.pl +68 -37
@@ -325,10 +325,10 @@ sub output_feature { # Output all features for all architectures # -sub matrix_lines($$) { - my $partial = shift; +sub matrix_lines($$$) { + my $desc_size = shift; + my $status_size = shift; my $header = shift; - my $split; my $fill; my $ln_marker;
@@ -338,24 +338,14 @@ sub matrix_lines($$) { $ln_marker = "-"; } - if ($partial) { - $split = "|"; - $fill = " "; - } else { - $split = "+"; - $fill = $ln_marker; - } + $fill = $ln_marker; - print $split; + print "+"; print $fill x $max_size_name; - print $split; - print $fill x $max_size_kconfig; - print $split; - print $fill x $max_size_description; print "+"; - print $ln_marker x $max_size_arch; + print $fill x $desc_size; print "+"; - print $ln_marker x $max_size_status; + print $ln_marker x $status_size; print "+\n"; }
@@ -366,6 +356,14 @@ sub output_matrix { print "$title\n"; print "=" x length($title) . "\n\n"; + my $desc_title = "$h_kconfig / $h_description"; + + my $desc_size = $max_size_kconfig + 4; + $desc_size = $max_size_description if ($max_size_description > $desc_size); + $desc_size = length($desc_title) if (length($desc_title) > $desc_size); + + my $status_size = 60; + my $cur_subsys = ""; foreach my $name (sort { ($data{$a}->{subsys} cmp $data{$b}->{subsys}) or
@@ -383,36 +381,69 @@ sub output_matrix { print "$title\n"; print "=" x length($title) . "\n\n"; - matrix_lines(0, 0); + + matrix_lines($desc_size, $status_size, 0); + printf "|%-${max_size_name}s", $h_name; - printf "|%-${max_size_kconfig}s", $h_kconfig; - printf "|%-${max_size_description}s", $h_description; + printf "|%-${desc_size}s", $desc_title; - printf "|%-${max_size_arch}s", $h_arch; - printf "|%-${max_size_status}s|\n", $h_status; - - matrix_lines(0, 1); + printf "|%-${status_size}s|\n", "Status per architecture"; + matrix_lines($desc_size, $status_size, 1); } my %arch_table = %{$data{$name}->{table}}; - my $first = 1; - foreach my $arch (sort keys %arch_table) { - if ($first) { + my $cur_status = ""; + + my @lines; + my $line = ""; + foreach my $arch (sort { + ($arch_table{$a} cmp $arch_table{$b}) or + ("\L$a" cmp "\L$b") + } keys %arch_table) { + + my $status = $arch_table{$arch}; + + if ($status eq "---") { + $status = "Not compatible"; + } + + if ($status ne $cur_status) { + if ($line ne "") { + push @lines, $line; + $line = ""; + } + $line = "- **" . $status . "**: " . $arch; + } elsif (length($line) + length ($arch) + 2 < $status_size) { + $line .= ", " . $arch; + } else { + push @lines, $line; + $line = " " . $arch; + } + $cur_status = $status; + } + push @lines, $line if ($line ne ""); + + # Ensure that description will be printed + push @lines, "" while (scalar(@lines) < 2); + + my $ln = 0; + for my $line(@lines) { + if (!$ln) { printf "|%-${max_size_name}s", $name; - printf "|%-${max_size_kconfig}s", $data{$name}->{kconfig}; - printf "|%-${max_size_description}s", $data{$name}->{description}; - $first = 0; + printf "|%-${desc_size}s", "``" . $data{$name}->{kconfig} . "``"; + } elsif ($ln == 2) { + printf "|%-${max_size_name}s", ""; + printf "|%-${desc_size}s", $data{$name}->{description}; } else { - matrix_lines(1, 0); - printf "|%-${max_size_name}s", ""; - printf "|%-${max_size_kconfig}s", ""; - printf "|%-${max_size_description}s", ""; + printf "|%-${desc_size}s", ""; } - printf "|%-${max_size_arch}s", $arch; - printf "|%-${max_size_status}s|\n", $arch_table{$arch}; + + printf "|%-${status_size}s|\n", $line; + + $ln++; } - matrix_lines(0, 0); + matrix_lines($desc_size, $status_size, 0); } }
Signature · 1 line
2.28.0
PATCH v4 2/3 scripts: get_feat.pl: change the group by order
In reply to Mauro Carvalho ChehabRight now, arch compatibility is grouped by status at the alphabetical order from A to Z, and then from a to z, e. g:.
--- TODO ok
Revert the order, in order to print first the OK results, then TODO, and, finally, the not compatible ones.
--- scripts/get_feat.pl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
scripts/get_feat.pl +1 -1
@@ -397,7 +397,7 @@ sub output_matrix { my @lines; my $line = ""; foreach my $arch (sort { - ($arch_table{$a} cmp $arch_table{$b}) or + ($arch_table{$b} cmp $arch_table{$a}) or ("\L$a" cmp "\L$b") } keys %arch_table) {
Signature · 1 line
2.28.0
PATCH v4 3/3 scripts: get_feat.pl: reduce table width for all features output
In reply to Mauro Carvalho ChehabAuto-adjust the table columns width to better fit under terminals, by breaking the description on multiple lines and auto-estimating the minimal size for the per-architecture status.
--- scripts/get_feat.pl | 71 +++++++++++++++++++++++++++++++++++++-------- 1 file changed, 59 insertions(+), 12 deletions(-)
scripts/get_feat.pl +59 -12
@@ -19,6 +19,11 @@ $basename =~ s,/[^/]+$,/,; my $prefix=$basename . "../Documentation/features"; +# Used only at for full features output. The script will auto-adjust +# such values for the minimal possible values +my $status_size = 1; +my $description_size = 1; + GetOptions( "debug|d+" => \$debug, "dir=s" => \$prefix,
@@ -77,7 +82,10 @@ my $max_size_kconfig = length($h_kconfig); my $max_size_description = length($h_description); my $max_size_subsys = length($h_subsys); my $max_size_status = length($h_status); -my $max_size_arch = length($h_arch); + +my $max_size_arch = 0; +my $max_size_arch_with_header; +my $max_description_word = 0; sub parse_feat { my $file = $File::Find::name;
@@ -127,6 +135,13 @@ sub parse_feat { if (length($description) > $max_size_description) { $max_size_description = length($description); } + + foreach my $word (split /\s+/, $description) { + if (length($word) > $max_description_word) { + $max_description_word = length($word); + } + } + next; } next if (m/^\\s*$/);
@@ -180,6 +195,8 @@ sub parse_feat { $data{$name}->{description} = $description; $data{$name}->{comments} = $comments; $data{$name}->{table} = \%arch_table; + + $max_size_arch_with_header = $max_size_arch + length($h_arch); } #
@@ -296,7 +313,7 @@ sub output_feature { print "$com\n\n"; } - print "=" x $max_size_arch; + print "=" x $max_size_arch_with_header; print " "; print "=" x $max_size_status; print "\n";
@@ -304,7 +321,7 @@ sub output_feature { printf "%-${max_size_arch}s ", $h_arch; printf "%-${max_size_status}s", $h_status . "\n"; - print "=" x $max_size_arch; + print "=" x $max_size_arch_with_header; print " "; print "=" x $max_size_status; print "\n";
@@ -315,7 +332,7 @@ sub output_feature { printf "%-${max_size_status}s\n", $arch_table{$arch}; } - print "=" x $max_size_arch; + print "=" x $max_size_arch_with_header; print " "; print "=" x $max_size_status; print "\n";
@@ -351,6 +368,7 @@ sub matrix_lines($$$) { sub output_matrix { my $title = "Feature status on all architectures"; + my $notcompat = "Not compatible"; print "=" x length($title) . "\n"; print "$title\n";
@@ -359,10 +377,21 @@ sub output_matrix { my $desc_title = "$h_kconfig / $h_description"; my $desc_size = $max_size_kconfig + 4; - $desc_size = $max_size_description if ($max_size_description > $desc_size); + if (!$description_size) { + $desc_size = $max_size_description if ($max_size_description > $desc_size); + } else { + $desc_size = $description_size if ($description_size > $desc_size); + } + $desc_size = $max_description_word if ($max_description_word > $desc_size); + $desc_size = length($desc_title) if (length($desc_title) > $desc_size); - my $status_size = 60; + $max_size_status = length($notcompat) if (length($notcompat) > $max_size_status); + + # Ensure that the status will fit + my $min_status_size = $max_size_status + $max_size_arch + 6; + $status_size = $min_status_size if ($status_size < $min_status_size); + my $cur_subsys = ""; foreach my $name (sort {
@@ -394,7 +423,7 @@ sub output_matrix { my %arch_table = %{$data{$name}->{table}}; my $cur_status = ""; - my @lines; + my (@lines, @descs); my $line = ""; foreach my $arch (sort { ($arch_table{$b} cmp $arch_table{$a}) or
@@ -404,7 +433,7 @@ sub output_matrix { my $status = $arch_table{$arch}; if ($status eq "---") { - $status = "Not compatible"; + $status = $notcompat; } if ($status ne $cur_status) {
@@ -423,17 +452,35 @@ sub output_matrix { } push @lines, $line if ($line ne ""); - # Ensure that description will be printed - push @lines, "" while (scalar(@lines) < 2); + my $description = $data{$name}->{description}; + while (length($description) > $desc_size) { + my $d = substr $description, 0, $desc_size; + + # Ensure that it will end on a space + # if it can't, it means that the size is too small + # Instead of aborting it, let's print what we have + if (!($d =~ s/^(.*)\s+.*/$1/)) { + $d = substr $d, 0, -1; + push @descs, "$d\\"; + $description =~ s/^\Q$d\E//; + } else { + push @descs, $d; + $description =~ s/^\Q$d\E\s+//; + } + } + push @descs, $description; + + # Ensure that the full description will be printed + push @lines, "" while (scalar(@lines) < 2 + scalar(@descs)); my $ln = 0; for my $line(@lines) { if (!$ln) { printf "|%-${max_size_name}s", $name; printf "|%-${desc_size}s", "``" . $data{$name}->{kconfig} . "``"; - } elsif ($ln == 2) { + } elsif ($ln >= 2 && scalar(@descs)) { printf "|%-${max_size_name}s", ""; - printf "|%-${desc_size}s", $data{$name}->{description}; + printf "|%-${desc_size}s", shift @descs; } else { printf "|%-${max_size_name}s", ""; printf "|%-${desc_size}s", "";
Signature · 1 line
2.28.0
Jonathan Corbet
maintainerRe: [PATCH v4 0/3] improve get_feat.pl output when all features are displayed
In reply to Mauro Carvalho ChehabQuoted 10 lines · On Fri, 4 Dec 2020 16:32:27 +0100 Mauro Carvalho Chehab…
As requested, those patches improve the output of the script, when all features are displayed.
The first patch was already posted as-is at v3.
Patch 2 is optional. IMO, it makes more sense for the admin guide to show the architectures where the features are OK, then TODO, and finally the ones that are incompatible with the features. I already sent it together with a comment.
Quoted 6 lines
Patch 3 is new: it tries to reduce the width of the table, in order for it to better fit on a terminal. With the patch, the number of columns were reduced, in order to better fit at console output. Before the patch, the output takes 281 lines with 158 columns (total size: 38.9 kB). After the patch, displaying all features require 439 lines and 92 columns (total size: 37.6 kB).
OK, this is much improved, thanks; applied.
The one last thing I would do is stick "valign=top" on all the table entries, but we can leave the shed a different color for now :)
Thanks,
jon
Re: [PATCH v4 0/3] improve get_feat.pl output when all features are displayed
Em Fri, 4 Dec 2020 14:48:43 -0700
Jonathan Corbet <[email protected]> escreveu:
Quoted 13 lines
Quoted 10 lines · On Fri, 4 Dec 2020 16:32:27 +0100 Mauro Carvalho Chehab…
As requested, those patches improve the output of the script, when all features are displayed.
The first patch was already posted as-is at v3.
Patch 2 is optional. IMO, it makes more sense for the admin guide to show the architectures where the features are OK, then TODO, and finally the ones that are incompatible with the features. I already sent it together with a comment.
Quoted 8 lines
Quoted 6 lines
Patch 3 is new: it tries to reduce the width of the table, in order for it to better fit on a terminal. With the patch, the number of columns were reduced, in order to better fit at console output. Before the patch, the output takes 281 lines with 158 columns (total size: 38.9 kB). After the patch, displaying all features require 439 lines and 92 columns (total size: 37.6 kB).
OK, this is much improved, thanks; applied.
Anytime.
Quoted 3 lines
The one last thing I would do is stick "valign=top" on all the table entries, but we can leave the shed a different color for now :)
I actually prefer myself valign=center on tables ;-)
In any case, a change like that should be simple to do.
either adjust:
Documentation/sphinx-static/theme_overrides.css
to change it globally for all tables or create a "table_valign_top" CSS class on it, changing the script to add:
.. cssclass:: table_valign_top
Before each table.
Thanks,
Mauro
Re: [PATCH v4 0/3] improve get_feat.pl output when all features are displayed
Em Sat, 5 Dec 2020 17:03:50 +0100
Mauro Carvalho Chehab <[email protected]> escreveu:
Quoted 37 lines
Em Fri, 4 Dec 2020 14:48:43 -0700
Jonathan Corbet <[email protected]> escreveu:Quoted 13 lines
Quoted 10 lines · On Fri, 4 Dec 2020 16:32:27 +0100 Mauro Carvalho Chehab…
As requested, those patches improve the output of the script, when all features are displayed.
The first patch was already posted as-is at v3.
Patch 2 is optional. IMO, it makes more sense for the admin guide to show the architectures where the features are OK, then TODO, and finally the ones that are incompatible with the features. I already sent it together with a comment.
Quoted 8 lines
Quoted 6 lines
Patch 3 is new: it tries to reduce the width of the table, in order for it to better fit on a terminal. With the patch, the number of columns were reduced, in order to better fit at console output. Before the patch, the output takes 281 lines with 158 columns (total size: 38.9 kB). After the patch, displaying all features require 439 lines and 92 columns (total size: 37.6 kB).
OK, this is much improved, thanks; applied.
Anytime.
Quoted 3 lines
The one last thing I would do is stick "valign=top" on all the table entries, but we can leave the shed a different color for now :)
I actually prefer myself valign=center on tables ;-)
In any case, a change like that should be simple to do.
either adjust:
Quoted 8 lines
Documentation/sphinx-static/theme_overrides.cssto change it globally for all tables or create a "
table_valign_top" CSS class on it, changing the script to add:.. cssclass::
table_valign_topBefore each table.
Btw, if you want to play with changing the table alignment, the enclosed patch changes the alignment to use valign=top for all tables (and not only for the feature ones).
Don't forget to remove the old theme before testing the patch with:
$ rm $(find Documentation/output/ -name theme_overrides.css)
As sphinx (at least version 2.4.4) only writes it if the file doesn't exist.
Thanks,
Mauro
[PATCH] docs: use top-alignment for table cells
Change the table's default in order to align cells on the top, overriding the defaults found on Read the Docs Sphinx Theme.
Documentation/sphinx-static/theme_overrides.css +5 -0
@@ -42,6 +42,11 @@ p { font-size: 100%; } +/* use vertical alignment on tables */ +.rst-content table.docutils td, .rst-content table.field-list td, .wy-table td { + vertical-align: top; +} + /* Interim: Code-blocks with line nos - lines and line numbers don't line up. * see: https://github.com/rtfd/sphinx_rtd_theme/issues/419 */
Re: [PATCH v4 0/3] improve get_feat.pl output when all features are displayed
Em Mon, 7 Dec 2020 10:33:40 +0100
Mauro Carvalho Chehab <[email protected]> escreveu:
Quoted 53 lines
Em Sat, 5 Dec 2020 17:03:50 +0100
Mauro Carvalho Chehab <[email protected]> escreveu:Quoted 37 lines
Em Fri, 4 Dec 2020 14:48:43 -0700
Jonathan Corbet <[email protected]> escreveu:Quoted 13 lines
Quoted 10 lines · On Fri, 4 Dec 2020 16:32:27 +0100 Mauro Carvalho Chehab…
As requested, those patches improve the output of the script, when all features are displayed.
The first patch was already posted as-is at v3.
Patch 2 is optional. IMO, it makes more sense for the admin guide to show the architectures where the features are OK, then TODO, and finally the ones that are incompatible with the features. I already sent it together with a comment.
Quoted 8 lines
Quoted 6 lines
Patch 3 is new: it tries to reduce the width of the table, in order for it to better fit on a terminal. With the patch, the number of columns were reduced, in order to better fit at console output. Before the patch, the output takes 281 lines with 158 columns (total size: 38.9 kB). After the patch, displaying all features require 439 lines and 92 columns (total size: 37.6 kB).
OK, this is much improved, thanks; applied.
Anytime.
Quoted 3 lines
The one last thing I would do is stick "valign=top" on all the table entries, but we can leave the shed a different color for now :)
I actually prefer myself valign=center on tables ;-)
In any case, a change like that should be simple to do.
either adjust:
Quoted 8 lines
Documentation/sphinx-static/theme_overrides.cssto change it globally for all tables or create a "
table_valign_top" CSS class on it, changing the script to add:.. cssclass::
table_valign_topBefore each table.
Btw, if you want to play with changing the table alignment, the enclosed patch changes the alignment to use valign=top for all tables (and not only for the feature ones).
Quoted 7 lines
Don't forget to remove the old theme before testing the patch with:
$ rm $(find Documentation/output/ -name theme_overrides.css)As sphinx (at least version 2.4.4) only writes it if the file doesn't exist.
Btw, if you want to vertically align just some tables - like the ones produced by get_feat.pl, the enclosed patch should do the job.
-
PS.: It seems worth mentioning here, as others may find issues when trying to customize the Kernel-specific CSS styles.
It took me a while to find a way for the style to be properly applied, due to CSS Specificity[1].
[1] I don't usually deal with CSS style sheets :-) So, had to do some research and lots of tests.
Those are two useful references about that:
https://stackoverflow.com/questions/12258596/class-overrule-when-two-classes-assigned-to-one-div
https://www.smashingmagazine.com/2007/07/css-specificity-things-you-should-know/
The thing is that the tables (tested with Sphinx 2.4.4) are created with multiple classes:
<table class="top-aligned docutils align-default">
As the user-specified class (top-aligned) is the first one (instead of the last one), it has less precedence than "docutils" or "align-default" classes.
So, if one specifies at the CSS file just:
.top-aligned {
vertical-align: top;
color: red;
}The table color will change to red as expected, but the vertical-align will be overridden by the other classes.
So, we need to place all classes there, in order to increase the CSS Specificity:
table.top-aligned.docutils.align-default td {
vertical-align: top;
}Thanks,
Mauro
[PATCH] scripts: get_feat.pl: align tables vertically on top
In order to make the full features tables, align
them on the top.
Documentation/sphinx-static/theme_overrides.css +5 -0
@@ -42,6 +42,11 @@ p { font-size: 100%; } +/* use vertical alignment on tables */ +table.top-aligned.docutils.align-default td { + vertical-align: top; +} + /* Interim: Code-blocks with line nos - lines and line numbers don't line up. * see: https://github.com/rtfd/sphinx_rtd_theme/issues/419 */
scripts/get_feat.pl +1 -0
@@ -410,6 +410,7 @@ sub output_matrix { print "$title\n"; print "=" x length($title) . "\n\n"; + print ".. cssclass:: top-aligned\n\n"; matrix_lines($desc_size, $status_size, 0);