containers/podman
1
0
Fork 0
mirror of https://github.com/containers/podman.git synced 2026-02-05 06:45:31 +01:00
Code Issues Releases Wiki Activity

Revert "Change the syntax to not depend on jinja2."

Browse Source 
This reverts commit 9de737bf29.

Signed-off-by: Paul Holzinger <pholzing@redhat.com>
This commit is contained in:
Paul Holzinger
2025-09-11 19:00:17 +02:00
parent fd60d63bf4
commit bb422c8372
105 changed files with 576 additions and 575 deletions
Download Patch File Download Diff File Expand all files Collapse all files

102
hack/markdown-preprocess
View File

@@ -11,6 +11,7 @@ import glob
import os
import re
import sys
from jinja2 import Template
class Preprocessor():
"""
@@ -23,100 +24,6 @@ class Preprocessor():
self.pod_or_container = ''
self.used_by = {}
def render(self, text: str, context: dict) -> str:
"""
Renders the `text` handling the following extra formatting features:
```
<< if variable >>
...
<< endif >>
<< if not variable >>
...
<< else >>
...
<< endif >>
<< "foo" if variable else "bar" >>
```
Returns the rendered text.
"""
# Match << ... >>
TOK = re.compile(r"<<(.*?)>>", re.DOTALL)
out = []
pos = 0
stack = [] # each frame: {"active": bool, "seen_else": bool}
def is_active():
return all(f["active"] for f in stack)
def get_variable(name: str):
v = context.get(name, None)
if v is None:
raise ValueError(f"undefined variable: {name}")
return v
def truthy(name: str) -> bool:
name = name.strip()
if name.startswith("not "):
v = get_variable(name[4:].strip())
return not bool(v)
return bool(get_variable(name))
for m in TOK.finditer(text):
# write literal up to token
literal = text[pos:m.start()]
if is_active():
out.append(literal)
pos = m.end()
inner = m.group(1).strip()
# control blocks
if inner.startswith("if ") and len(inner[3:].strip().split(" ")) in [1, 2]:
cond = inner[3:].strip()
stack.append({"active": is_active() and truthy(cond), "seen_else": False})
continue
if inner == "else":
if not stack:
raise ValueError("`else` without `if`")
frame = stack[-1]
if frame["seen_else"]:
raise ValueError("multiple `else` in the same `if`")
frame["seen_else"] = True
parent_active = all(f["active"] for f in stack[:-1])
frame["active"] = parent_active and not frame["active"]
continue
if inner == "endif":
if not stack:
raise ValueError("`end` without `if`")
stack.pop()
continue
# inline "X if cond else Y" ---
if " if " in inner and " else " in inner:
try:
# split by " if " then " else "
then_part, rest = inner.split(" if ", 1)
cond, else_part = rest.split(" else ", 1)
cond = cond.strip()
chosen = then_part if truthy(cond) else else_part
if is_active():
out.append(chosen.strip().strip("'\""))
except Exception as e:
raise ValueError(f"Invalid inline if/else syntax: {inner}") from e
continue
# trailing literal
if is_active():
out.append(text[pos:])
if stack:
raise ValueError("unclosed `if` block(s)")
return "".join(out)
def process(self, infile:str):
"""
Main calling point: preprocesses one file
@@ -198,7 +105,12 @@ class Preprocessor():
# comment in its output.
fh_out.write("\n[//]: # (BEGIN included file " + path + ")\n")
with open(path, 'r', encoding='utf-8') as fh_included:
rendered = self.render(fh_included.read(), {"is_quadlet": is_quadlet})
template = Template(fh_included.read(), variable_start_string='{{{', variable_end_string='}}}')
rendered = template.render(
is_quadlet=is_quadlet,
subcommand=self.podman_subcommand,
fullsubcommand=self.podman_subcommand('full')
)
for opt_line in rendered.splitlines():
if opt_line.startswith('####>'):
continue

134
hack/xref-quadlet-docs
View File

@@ -19,16 +19,7 @@ our $VERSION = '0.1';
# BEGIN user-customizable section
our $Go = 'pkg/systemd/quadlet/quadlet.go';
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",
);
our $Doc = 'docs/source/markdown/podman-systemd.unit.5.md';
# END user-customizable section
###############################################################################
@@ -44,7 +35,7 @@ $ME cross-checks quadlet documentation between the Go source[Go]
and the man page[MD].
[Go]: $Go
[MD]: @Docs
[MD]: $Doc
We check that:
@@ -104,7 +95,7 @@ sub main {
my $true_keys = read_go($Go);
# Read md file, compare against Truth
crossref_docs(\@Docs, $true_keys);
crossref_doc($Doc, $true_keys);
exit $errs;
}
@@ -150,17 +141,19 @@ sub read_go {
}
##################
# crossref_docs # Read the markdown pages, cross-check against Truth
# crossref_doc # Read the markdown page, cross-check against Truth
##################
sub crossref_docs {
my $paths_ref = shift; # in: array with paths to .md file
sub crossref_doc {
my $path = shift; # in: path 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
@@ -173,86 +166,85 @@ sub crossref_docs {
}
};
# foreach loop
foreach my $path (@$paths_ref) {
open my $fh, '<', $path
or die "$ME: Cannot read $path: $!\n";;
# Main loop: read the docs line by line
while (my $line = <$fh>) {
chomp $line;
my $new_unit = $path;
$crossref_against_table->();
$unit = $new_unit;
# 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";
# Reset, because each section has its own table & blocks
@found_in_table = ();
@described = ();
$read_first_table = 0;
$crossref_against_table->();
$unit = $new_unit;
# Main loop: read the docs line by line
while (my $line = <$fh>) {
chomp $line;
# Reset, because each section has its own table & blocks
@found_in_table = ();
@described = ();
next;
}
# Table line
if ($read_first_table == 0 && $line =~ s/^\|\s+//) {
next if $line =~ /^\*\*/; # title
next if $line =~ /^-----/; # divider
# Table line
if ($line =~ s/^\|\s+//) {
next if $line =~ /^\*\*/; # title
next if $line =~ /^-----/; # divider
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]+)=.*`/) {
if ($line =~ /^([A-Z][A-Za-z6]+)=/) {
my $key = $1;
$read_first_table = 1;
grep { $_ eq $key } @$true_keys
or warn "$ME: $path:$.: unknown key '$key' (not present in $Go)\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";
# 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";
}
}
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;
push @found_in_table, $key;
$documented{$key}++;
}
else {
warn "$ME: $path:$.: cannot grok table line '$line'\n";
}
}
close $fh;
# 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;
# 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 @$paths_ref\n";
or warn "$ME: undocumented key: '$k' not found anywhere in $md_basename\n";
}
}