mirror of
https://github.com/containers/podman.git
synced 2025-08-06 19:44:14 +08:00
5ea4ebb163
go-md2man happily ignores our comment lines in most cases,
but sphinx (used in readthedocs) cannot deal with comments
if they immediately follow any other content line:
blah blah
[//]: # (my comment)
...the whole comment line is actually rendered in its output.
Only solution seems to be to add extra newlines before each
comment. Makes diff and PR review harder, but otherwise has
no effect on the rendered documents.
Signed-off-by: Ed Santiago <santiago@redhat.com>
86 lines
3.1 KiB
Python
Executable File
86 lines
3.1 KiB
Python
Executable File
#!/usr/bin/env python3
|
|
#
|
|
# markdown-preprocess - filter *.md.in files, convert to .md
|
|
#
|
|
|
|
import glob
|
|
import os
|
|
import sys
|
|
|
|
def main():
|
|
script_dir = os.path.abspath(os.path.dirname(__file__))
|
|
man_dir = os.path.join(script_dir,"../docs/source/markdown")
|
|
|
|
try:
|
|
os.chdir(man_dir)
|
|
except FileNotFoundError:
|
|
raise Exception("Please invoke me from the base repo dir")
|
|
|
|
# If called with args, process only those files
|
|
infiles = [ os.path.basename(x) for x in sys.argv[1:] ]
|
|
if len(infiles) == 0:
|
|
# Called without args: process all *.md.in files
|
|
infiles = glob.glob('*.md.in')
|
|
for infile in infiles:
|
|
process(infile)
|
|
|
|
def process(infile):
|
|
# Some options are the same between containers and pods; determine
|
|
# which description to use from the name of the source man page.
|
|
pod_or_container = 'container'
|
|
if '-pod-' in infile:
|
|
pod_or_container = 'pod'
|
|
|
|
# Sometimes a man page includes the subcommand.
|
|
subcommand = removesuffix(removeprefix(infile,"podman-"),".1.md.in").replace("-", " ")
|
|
|
|
# foo.md.in -> foo.md -- but always write to a tmpfile
|
|
outfile = os.path.splitext(infile)[0]
|
|
outfile_tmp = outfile + '.tmp.' + str(os.getpid())
|
|
|
|
# print("got here: ",infile, " -> ", outfile)
|
|
|
|
with open(infile, 'r') as fh_in, open(outfile_tmp, 'w') 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')
|
|
|
|
# Comment intended to help someone viewing the .md file.
|
|
# Leading newline is important because if two lines are
|
|
# consecutive without a break, sphinx (but not go-md2man)
|
|
# treats them as one line and will unwantedly render the
|
|
# comment in its output.
|
|
fh_out.write("\n[//]: # (BEGIN included file " + optionfile + ")\n")
|
|
with open(optionfile, 'r') as fh_optfile:
|
|
for opt_line in fh_optfile:
|
|
opt_line = opt_line.replace('<POD-OR-CONTAINER>', pod_or_container)
|
|
opt_line = opt_line.replace('<SUBCOMMAND>', subcommand)
|
|
fh_out.write(opt_line)
|
|
fh_out.write("\n[//]: # (END included file " + optionfile + ")\n")
|
|
else:
|
|
fh_out.write(line)
|
|
|
|
os.chmod(outfile_tmp, 0o444)
|
|
os.rename(outfile_tmp, outfile)
|
|
|
|
# str.removeprefix() is python 3.9+, we need to support older versions on mac
|
|
def removeprefix(string: str, prefix: str) -> str:
|
|
if string.startswith(prefix):
|
|
return string[len(prefix):]
|
|
else:
|
|
return string[:]
|
|
|
|
# str.removesuffix() is python 3.9+, we need to support older versions on mac
|
|
def removesuffix(string: str, suffix: str) -> str:
|
|
# suffix='' should not call self[:-0].
|
|
if suffix and string.endswith(suffix):
|
|
return string[:-len(suffix)]
|
|
else:
|
|
return string[:]
|
|
|
|
|
|
if __name__ == "__main__":
|
|
main()
|