From 5ea4ebb1630277956d794d6c393ee0f29f09ed1d Mon Sep 17 00:00:00 2001 From: Ed Santiago Date: Thu, 4 Aug 2022 08:38:29 -0600 Subject: markdown-preprocess: force extra newline on comments 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 --- hack/markdown-preprocess | 18 ++++++++---------- 1 file changed, 8 insertions(+), 10 deletions(-) (limited to 'hack/markdown-preprocess') diff --git a/hack/markdown-preprocess b/hack/markdown-preprocess index 6d2675cc4..4bc67a819 100755 --- a/hack/markdown-preprocess +++ b/hack/markdown-preprocess @@ -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) opt_line = opt_line.replace('', 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) -- cgit v1.2.3-54-g00ecf