doc/bst2html.py: Add support for `fake-output` when running commands.

When specifying a fake-output string, we don't really run the command
or assume it was a `bst` command, and we pretend that `fake-output`
was the output of the command.

Specifying an empty string explicitly enables the behavior too
for faking a command that has no stdout/stderr.

This also adds the "remove-files" hack allowing the session scripts
to remove files before executing commands (kind of unsure if we're
gonna keep this...)

2 files changed, 49 insertions, 21 deletions

diff --git a/HACKING.rst b/HACKING.rst
index d326a7b35..1c9624090 100644
--- a/HACKING.rst
+++ b/HACKING.rst
@@ -383,6 +383,9 @@ Each *command* is a dictionary, the members of which are listed here:
 
 * ``output``: The input file relative output html file to generate (optional)
 
+* ``fake-output``: Don't really run the command, just pretend to and pretend
+  this was the output, an empty string will enable this too.
+
 * ``command``: The command to run, without the leading ``bst``
 
 When adding a new ``.run`` file, one should normally also commit the new
diff --git a/doc/bst2html.py b/doc/bst2html.py
index 9c5aaaf9a..9624b301f 100755
--- a/doc/bst2html.py
+++ b/doc/bst2html.py
@@ -36,6 +36,7 @@ from tempfile import TemporaryDirectory
 import click
 
 from buildstream import _yaml
+from buildstream import utils
 from buildstream._exceptions import BstError
 
 
@@ -188,6 +189,8 @@ def ansi2html(text, palette='solarized'):
 @contextmanager
 def workdir(source_cache=None):
     with TemporaryDirectory(prefix='run-bst-', dir=os.getcwd()) as tempdir:
+        if not source_cache:
+            source_cache = os.path.join(tempdir, 'sources')
 
         bst_config_file = os.path.join(tempdir, 'buildstream.conf')
         config = {
@@ -198,7 +201,7 @@ def workdir(source_cache=None):
         }
         _yaml.dump(config, bst_config_file)
 
-        yield (tempdir, bst_config_file)
+        yield (tempdir, bst_config_file, source_cache)
 
 
 # run_command()
@@ -234,14 +237,18 @@ def run_command(config_file, directory, command):
 #    tempdir (str): The base work directory
 #    palette (str): The rendering color style
 #    command (str): The command
+#    fake_output (bool): Whether the provided output is faked or not
 #
 # Returns:
 #    (str): The html formatted output
 #
-def generate_html(output, directory, config_file, source_cache, tempdir, palette, command):
+def generate_html(output, directory, config_file, source_cache, tempdir, palette, command, fake_output):
 
     test_base_name = os.path.basename(directory)
-    show_command = 'bst ' + command
+    if fake_output:
+        show_command = command
+    else:
+        show_command = 'bst ' + command
 
     # Substitute some things we want normalized for the docs
     output = re.sub(os.environ.get('HOME'), '/home/user', output)
@@ -254,18 +261,21 @@ def generate_html(output, directory, config_file, source_cache, tempdir, palette
     output = ansi2html(output, palette=palette)
 
     # Finally format it nicely into a <div>
-    output = '<!--\n' + \
-             '    WARNING: This file was generated with bst2html.py\n' + \
-             '-->\n' + \
-             '<div class="highlight" style="font-size:x-small">' + \
-             '<pre>\n' + \
-             '<span style="color:#C4A000;font-weight:bold">user@host</span>:' + \
-             '<span style="color:#3456A4;font-weight:bold">~/{}</span>$ '.format(test_base_name) + \
-             show_command + '\n\n' + \
-             output + '\n' + \
-             '</pre></div>\n'
+    final_output = '<!--\n' + \
+                   '    WARNING: This file was generated with bst2html.py\n' + \
+                   '-->\n' + \
+                   '<div class="highlight" style="font-size:x-small">' + \
+                   '<pre>\n' + \
+                   '<span style="color:#C4A000;font-weight:bold">user@host</span>:' + \
+                   '<span style="color:#3456A4;font-weight:bold">~/{}</span>$ '.format(test_base_name) + \
+                   show_command + '\n'
+
+    if output:
+        final_output += '\n' + output + '\n'
 
-    return output
+    final_output += '</pre></div>\n'
+
+    return final_output
 
 
 def run_session(description, tempdir, source_cache, palette, config_file):
@@ -298,6 +308,16 @@ def run_session(description, tempdir, source_cache, palette, config_file):
             # not a source distribution, no need to complain
             pass
 
+    remove_files = _yaml.node_get(desc, list, 'remove-files', default_value=[])
+    for remove_file in remove_files:
+        remove_file = os.path.join(desc_dir, remove_file)
+        remove_file = os.path.realpath(remove_file)
+
+        if os.path.isdir(remove_file):
+            utils._force_rmtree(remove_file)
+        else:
+            utils.safe_remove(remove_file)
+
     # Run commands
     #
     commands = _yaml.node_get(desc, list, 'commands')
@@ -309,9 +329,17 @@ def run_session(description, tempdir, source_cache, palette, config_file):
         directory = os.path.join(desc_dir, directory)
         directory = os.path.realpath(directory)
 
-        # Run the command
+        # Get the command string
         command_str = _yaml.node_get(command, str, 'command')
-        command_out = run_command(config_file, directory, command_str)
+
+        # Check if there is fake output
+        command_fake_output = _yaml.node_get(command, str, 'fake-output', default_value=None)
+
+        # Run the command, or just use the fake output
+        if command_fake_output is None:
+            command_out = run_command(config_file, directory, command_str)
+        else:
+            command_out = command_fake_output
 
         # Encode and save the output if that was asked for
         output = _yaml.node_get(command, str, 'output', default_value=None)
@@ -320,7 +348,7 @@ def run_session(description, tempdir, source_cache, palette, config_file):
             # Convert / Generate a nice <div>
             converted = generate_html(command_out, directory, config_file,
                                       source_cache, tempdir, palette,
-                                      command_str)
+                                      command_str, command_fake_output is not None)
 
             # Save it
             filename = os.path.join(desc_dir, output)
@@ -359,10 +387,7 @@ def run_bst(directory, source_cache, description, palette, output, command):
     if not source_cache and os.environ.get('BST_SOURCE_CACHE'):
         source_cache = os.environ['BST_SOURCE_CACHE']
 
-    with workdir(source_cache=source_cache) as (tempdir, config_file):
-
-        if not source_cache:
-            source_cache = os.path.join(tempdir, 'sources')
+    with workdir(source_cache=source_cache) as (tempdir, config_file, source_cache):
 
         if description:
             run_session(description, tempdir, source_cache, palette, config_file)