From c48b03ca9c69f764476fd3809074ab1645beba65 Mon Sep 17 00:00:00 2001
From: Emmanuel Lepage Vallee <elv1313@gmail.com>
Date: Thu, 27 Jun 2019 02:17:07 -0400
Subject: [PATCH] doc: Help the examples with text but no images get generated
 more often.

In case of error, well, make an error, but update the content anyway.
This will be enough for the CI but makes development less painful.

Also update the cmake targets to re-generate them more often.
---
 tests/examples/CMakeLists.txt | 53 ++++++++++++++++++++++++++---------
 tests/examples/runner.sh      |  1 +
 2 files changed, 40 insertions(+), 14 deletions(-)

diff --git a/tests/examples/CMakeLists.txt b/tests/examples/CMakeLists.txt
index c4eef2552..3d2a81ed6 100644
--- a/tests/examples/CMakeLists.txt
+++ b/tests/examples/CMakeLists.txt
@@ -232,15 +232,23 @@ function(run_test test_path namespace escaped_content)
             file(READ "${expected_output_path}" expected_output)
         endif()
 
-        set(TEST_DOC_CONTENT
-            "${TEST_DOC_CONTENT}\n${DOC_LINE_PREFIX}\n${DOC_LINE_PREFIX}**Usage example output**:\n${DOC_LINE_PREFIX}"
-        )
+        if (NOT tmp_content MATCHES "--DOC_RAW_OUTPUT")
+            set(TEST_DOC_CONTENT
+                "${TEST_DOC_CONTENT}\n${DOC_LINE_PREFIX}\n${DOC_LINE_PREFIX}**Usage example output**:\n${DOC_LINE_PREFIX}"
+            )
+
+            # Markdown requires an empty line before and after, and 4 spaces.
+            escape_string(
+                "\n${expected_output}"
+                "${TEST_DOC_CONTENT}" TEST_DOC_CONTENT "    "
+            )
+        else()
+            escape_string(
+                "\n${expected_output}"
+                "${TEST_DOC_CONTENT}" TEST_DOC_CONTENT ""
+            )
+        endif()
 
-        # Markdown requires an empty line before and after, and 4 spaces.
-        escape_string(
-            "\n${expected_output}"
-            "${TEST_DOC_CONTENT}" TEST_DOC_CONTENT "    "
-        )
         set(TEST_DOC_CONTENT "${TEST_DOC_CONTENT}\n${DOC_LINE_PREFIX}")
     endif()
 
@@ -270,14 +278,31 @@ function(run_test test_path namespace escaped_content)
 
     if(NOT ${OUTPUT_IMAGE_PATH} STREQUAL "")
         file(RELATIVE_PATH rel_output "${TOP_SOURCE_DIR}" "${OUTPUT_IMAGE_PATH}")
-        add_custom_command(
-            COMMAND "${TOP_SOURCE_DIR}/tests/examples/runner.sh" "${expected_output_path}" ${LUA_COV_RUNNER} ${template} ${test_path} ${IMAGE_PATH} ${IGNORE_ERRORS}
-            # COMMENT "Running ${rel_test_path} (via ${rel_template}, generating ${rel_output})"
-            DEPENDS ${template} ${test_path}
-            OUTPUT  ${OUTPUT_IMAGE_PATH}
-            VERBATIM)
+        if(tmp_content MATCHES "--DOC_GEN_OUTPUT")
+            add_custom_command(
+                COMMAND "${TOP_SOURCE_DIR}/tests/examples/runner.sh" "${expected_output_path}" ${LUA_COV_RUNNER} ${template} ${test_path} ${IMAGE_PATH} ${IGNORE_ERRORS}
+                # COMMENT "Running ${rel_test_path} (via ${rel_template}, generating ${rel_output})"
+                DEPENDS ${template} ${test_path}
+                OUTPUT  ${OUTPUT_IMAGE_PATH}
+                OUTPUT  ${expected_output_path}
+                VERBATIM)
+        else()
+            add_custom_command(
+                COMMAND "${TOP_SOURCE_DIR}/tests/examples/runner.sh" "${expected_output_path}" ${LUA_COV_RUNNER} ${template} ${test_path} ${IMAGE_PATH} ${IGNORE_ERRORS}
+                # COMMENT "Running ${rel_test_path} (via ${rel_template}, generating ${rel_output})"
+                DEPENDS ${template} ${test_path}
+                OUTPUT  ${OUTPUT_IMAGE_PATH}
+                VERBATIM)
+        endif()
         set(EXAMPLE_DOC_GENERATED_FILES ${OUTPUT_IMAGE_PATH} ${EXAMPLE_DOC_GENERATED_FILES}
             PARENT_SCOPE)
+    elseif(tmp_content MATCHES "--DOC_GEN_OUTPUT")
+        add_custom_command(
+            COMMAND "${TOP_SOURCE_DIR}/tests/examples/runner.sh" "${expected_output_path}" ${LUA_COV_RUNNER} ${template} ${test_path} "" ${IGNORE_ERRORS}
+            # COMMENT "Running ${rel_test_path} (via ${rel_template}, generating ${rel_output})"
+            DEPENDS ${template} ${test_path}
+            OUTPUT ${expected_output_path}
+            VERBATIM)
     endif()
 
     # Export the outout to the parent scope.
diff --git a/tests/examples/runner.sh b/tests/examples/runner.sh
index 2c1e7022e..3084e934b 100755
--- a/tests/examples/runner.sh
+++ b/tests/examples/runner.sh
@@ -49,6 +49,7 @@ if ! cmp --silent "${file_stdout}" "${expected_output}"
 then
     echo "Expected text from ${expected_output}, but got:"
     diff -u "${expected_output}" "${file_stdout}" || true
+    cp "${file_stdout}" "${expected_output}"
     exit 1
 fi