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 <santiago@redhat.com>

1 files changed, 8 insertions, 10 deletions

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>', 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)