opensource/podman
1
0
Fork 0
mirror of https://github.com/containers/podman.git synced 2025-09-21 03:35:06 +08:00
Code Issues Packages Projects Releases Wiki Activity

Change the syntax to not depend on jinja2.

Browse Source 
Signed-off-by: Jan Kaluza <jkaluza@redhat.com>
This commit is contained in:
Jan Kaluza
2025-09-02 12:12:24 +02:00
parent c12b1b32bc
commit 9de737bf29
105 changed files with 575 additions and 576 deletions
Download Patch File Download Diff File Expand all files Collapse all files

134
hack/xref-quadlet-docs
View File

@ -19,7 +19,16 @@ our $VERSION = '0.1';
# BEGIN user-customizable section
our $Go = 'pkg/systemd/quadlet/quadlet.go';
our $Doc = 'docs/source/markdown/podman-systemd.unit.5.md';
our @Docs = (
"docs/source/markdown/podman-build.unit.5.md",
"docs/source/markdown/podman-container.unit.5.md",
"docs/source/markdown/podman-kube.unit.5.md",
"docs/source/markdown/podman-network.unit.5.md",
"docs/source/markdown/podman-pod.unit.5.md",
"docs/source/markdown/podman-volume.unit.5.md",
"docs/source/markdown/podman-image.unit.5.md",
"docs/source/markdown/podman-quadlet.7.md",
);
# END user-customizable section
###############################################################################
@ -35,7 +44,7 @@ $ME cross-checks quadlet documentation between the Go source[Go]
and the man page[MD].
[Go]: $Go
[MD]: $Doc
[MD]: @Docs
We check that:
@ -95,7 +104,7 @@ sub main {
my $true_keys = read_go($Go);
# Read md file, compare against Truth
crossref_doc($Doc, $true_keys);
crossref_docs(\@Docs, $true_keys);
exit $errs;
}
@ -141,19 +150,17 @@ sub read_go {
}
##################
# crossref_doc # Read the markdown page, cross-check against Truth
# crossref_docs # Read the markdown pages, cross-check against Truth
##################
sub crossref_doc {
my $path = shift; # in: path to .md file
sub crossref_docs {
my $paths_ref = shift; # in: array with paths to .md file
my $true_keys = shift; # in: AREF, list of keys from .go
open my $fh, '<', $path
or die "$ME: Cannot read $path: $!\n";;
my $unit = '';
my %documented;
my @found_in_table;
my @described;
my $read_first_table;
# Helper function: when done reading description blocks,
# make sure that there's one block for each key listed
@ -166,85 +173,86 @@ sub crossref_doc {
}
};
# Main loop: read the docs line by line
while (my $line = <$fh>) {
chomp $line;
# foreach loop
foreach my $path (@$paths_ref) {
open my $fh, '<', $path
or die "$ME: Cannot read $path: $!\n";;
# New section, with its own '| table |' and '### Keyword blocks'
if ($line =~ /^##\s+(\S+)\s+(?:units|section)\s+\[(\S+)\]/) {
my $new_unit = $1;
$new_unit eq $2
or warn "$ME: $path:$.: inconsistent block names in '$line'\n";
my $new_unit = $path;
$crossref_against_table->();
$unit = $new_unit;
$crossref_against_table->();
# Reset, because each section has its own table & blocks
@found_in_table = ();
@described = ();
$read_first_table = 0;
$unit = $new_unit;
# Reset, because each section has its own table & blocks
@found_in_table = ();
@described = ();
next;
}
# Main loop: read the docs line by line
while (my $line = <$fh>) {
chomp $line;
# Table line
if ($line =~ s/^\|\s+//) {
next if $line =~ /^\*\*/; # title
next if $line =~ /^-----/; # divider
# Table line
if ($read_first_table == 0 && $line =~ s/^\|\s+//) {
next if $line =~ /^\*\*/; # title
next if $line =~ /^-----/; # divider
if ($line =~ /^([A-Z][A-Za-z6]+)=/) {
if ($line =~ /^([A-Z][A-Za-z6]+)=/) {
my $key = $1;
grep { $_ eq $key } @$true_keys
or warn "$ME: $path:$.: unknown key '$key' (not present in $Go)\n";
# Sorting check
if (@found_in_table) {
if (lc($key) lt lc($found_in_table[-1])) {
warn "$ME: $path:$.: out-of-order key '$key' in table\n";
}
}
push @found_in_table, $key;
$documented{$key}++;
}
else {
warn "$ME: $path:$.: cannot grok table line '$line'\n";
}
}
# Description block
elsif ($line =~ /^###\s+`([A-Z][A-Za-z6]+)=.*`/) {
my $key = $1;
grep { $_ eq $key } @$true_keys
or warn "$ME: $path:$.: unknown key '$key' (not present in $Go)\n";
$read_first_table = 1;
# Sorting check
if (@found_in_table) {
if (lc($key) lt lc($found_in_table[-1])) {
warn "$ME: $path:$.: out-of-order key '$key' in table\n";
# Check for dups and for out-of-order
if (@described) {
if (lc($key) lt lc($described[-1])) {
warn "$ME: $path:$.: out-of-order key '$key'\n";
}
if (grep { lc($_) eq lc($key) } @described) {
warn "$ME: $path:$.: duplicate key '$key'\n";
}
}
push @found_in_table, $key;
grep { $_ eq $key } @found_in_table
or warn "$ME: $path:$.: key '$key' is not listed in table for unit/section '$unit'\n";
push @described, $key;
$documented{$key}++;
}
else {
warn "$ME: $path:$.: cannot grok table line '$line'\n";
}
}
# Description block
elsif ($line =~ /^###\s+`(\S+)=`/) {
my $key = $1;
# Check for dups and for out-of-order
if (@described) {
if (lc($key) lt lc($described[-1])) {
warn "$ME: $path:$.: out-of-order key '$key'\n";
}
if (grep { lc($_) eq lc($key) } @described) {
warn "$ME: $path:$.: duplicate key '$key'\n";
}
}
grep { $_ eq $key } @found_in_table
or warn "$ME: $path:$.: key '$key' is not listed in table for unit/section '$unit'\n";
push @described, $key;
$documented{$key}++;
}
close $fh;
}
close $fh;
# Final cross-check between table and description blocks
$crossref_against_table->();
# Check that no Go keys are missing
(my $md_basename = $path) =~ s|^.*/||;
for my $k (@$true_keys) {
$documented{$k}
or warn "$ME: undocumented key: '$k' not found anywhere in $md_basename\n";
or warn "$ME: undocumented key: '$k' not found anywhere in @$paths_ref\n";
}
}