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

markdown-preprocess: force extra newline on comments

Browse Source 
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>
This commit is contained in:
Ed Santiago
2022-08-04 08:38:29 -06:00
parent 1cf6afb788
commit 5ea4ebb163
1 changed files with 8 additions and 10 deletions
Download Patch File Download Diff File Expand all files Collapse all files

18
hack/markdown-preprocess
View File

@ -46,21 +46,19 @@ def process(infile):
if line.startswith('@@option '):
_, optionname = line.strip().split(" ")
optionfile = os.path.join("options", optionname + '.md')
fh_out.write("[//]: # (BEGIN included file " + optionfile + ")\n")
# 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)
# Weird special case: options/image-volume.md ends in a
# list, and in markdown lists are continued across lines,
# so without an intervening blank line the '[//]' comment
# becomes part of the final list entry.
if opt_line.startswith('-'):
fh_out.write("\n")
fh_out.write("[//]: # (END included file " + optionfile + ")\n")
fh_out.write("\n[//]: # (END included file " + optionfile + ")\n")
else:
fh_out.write(line)