opensource/podman
1
0
Fork 0
mirror of https://github.com/containers/podman.git synced 2025-10-13 17:26:13 +08:00
Code Issues Packages Projects Releases Wiki Activity

Rewrite the Quadlet documentation.

Browse Source 
This commit does the following:

- Splits the podman-systemd.unit.5.md into multiple files - one for each
  quadlet file type, podman-quadlet.7.md for general quadlet information
  and podman-quadlet-basic-usage.7.md for quadlet examples.
- Removes the original podman-systemd.unit.5.md file.
- Adds support for jinja2 templating language in the markdown_preprocess.
- Uses jinja2 in options/*.md to use the single .md file for both podman
  subcommands man-pages and quadlet man-pages. This deduplicates
  the Quadlet man-pages a lot.
- Adds new `@@option quadlet:source.md` preprocess command to import
  such .md files from options directory.

Signed-off-by: Jan Kaluza <jkaluza@redhat.com>
This commit is contained in:
Jan Kaluza
2025-08-19 12:52:17 +02:00
parent fcdb6b59d9
commit c12b1b32bc
109 changed files with 2738 additions and 2447 deletions
Download Patch File Download Diff File Expand all files Collapse all files

47
hack/markdown-preprocess
View File

@ -11,6 +11,7 @@ import glob
import os
import re
import sys
from jinja2 import Template
class Preprocessor():
"""
@ -40,18 +41,24 @@ class Preprocessor():
with open(infile, 'r', encoding='utf-8') as fh_in, open(outfile_tmp, 'w', encoding='utf-8', newline='\n') as fh_out:
for line in fh_in:
# '@@option foo' -> include file options/foo.md
if line.startswith('@@option '):
_, optionname = line.strip().split(" ")
optionfile = os.path.join("options", optionname + '.md')
self.track_optionfile(optionfile)
self.insert_file(fh_out, optionfile)
# '@@include relative-path/must-exist.md'
elif line.startswith('@@include '):
_, path = line.strip().split(" ")
self.insert_file(fh_out, path)
else:
fh_out.write(line)
try:
# '@@option foo' -> include file options/foo.md
if line.startswith('@@option '):
_, optionname = line.strip().split(" ")
is_quadlet = optionname.startswith("quadlet:")
if is_quadlet:
optionname = optionname[len("quadlet:"):]
optionfile = os.path.join("options", optionname + '.md')
self.track_optionfile(optionfile)
self.insert_file(fh_out, optionfile, is_quadlet)
# '@@include relative-path/must-exist.md'
elif line.startswith('@@include '):
_, path = line.strip().split(" ")
self.insert_file(fh_out, path)
else:
fh_out.write(line)
except Exception as ex:
raise Exception(f"Error while processing {infile} line '{line[:-1]}'") from ex
os.chmod(outfile_tmp, 0o444)
os.rename(outfile_tmp, outfile)
@ -87,7 +94,7 @@ class Preprocessor():
else:
os.unlink(tmpfile)
def insert_file(self, fh_out, path: str):
def insert_file(self, fh_out, path: str, is_quadlet=False):
"""
Reads one option file, writes it out to the given output filehandle
"""
@ -98,13 +105,20 @@ 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:
for opt_line in fh_included:
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
opt_line = self.replace_type(opt_line)
opt_line = opt_line.replace('<<subcommand>>', self.podman_subcommand())
opt_line = opt_line.replace('<<fullsubcommand>>', self.podman_subcommand('full'))
fh_out.write(opt_line)
fh_out.write(opt_line + '\n')
fh_out.write("\n[//]: # (END included file " + path + ")\n")
def podman_subcommand(self, full=None) -> str:
@ -117,6 +131,9 @@ class Preprocessor():
if not full:
if subcommand.startswith("podman-pod-"):
subcommand = subcommand[len("podman-pod-"):]
# For quadlet man-pages, the subcommand is simply the full manpage name.
if subcommand.endswith(".unit.5.md.in"):
return subcommand
if subcommand.startswith("podman-"):
subcommand = subcommand[len("podman-"):]
if subcommand.endswith(".1.md.in"):