Allow building of the docs without rerunning the sessionswillsalmon/sessionsBug

4 files changed, 26 insertions, 8 deletions

diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index 4e8603a82..bd1c533f2 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -172,11 +172,13 @@ docs:
   - make BST_FORCE_SESSION_REBUILD=1 -C doc
   - cd ../..
   - mv dist/buildstream/doc/build/html public
+  - mv dist/buildstream/doc/source/sessions session-output
   except:
   - schedules
   artifacts:
     paths:
     - public/
+    - session-output
 
 .overnight-tests: &overnight-tests-template
   stage: test
diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
index da8bcab77..396e92458 100644
--- a/CONTRIBUTING.rst
+++ b/CONTRIBUTING.rst
@@ -1247,12 +1247,21 @@ To build the documentation, just run the following::
 This will give you a ``doc/build/html`` directory with the html docs which
 you can view in your browser locally to test.
 
-
 Regenerating session html
 '''''''''''''''''''''''''
-The documentation build will build the session files if they are missing,
-or if explicitly asked to rebuild. We revision the generated session html files
-in order to reduce the burden on documentation contributors.
+The documentation build will build the session files if the html is out of date
+or missing, or if explicitly asked to rebuild.
+
+You can skip running the session files and have dummy examples generated to allow
+changes to the documentation to be render if a user is unable to regenerate the
+session files them selves.
+
+  make BST_DUMMY_REBUILD=1 -C doc
+
+If a user would like to create the docs with the correct session output but is
+unable to run the session files then they may down load the latest session files
+from the gitlab-ci doc element of the master ci PIPELINE and copy them in to the
+doc/source/sessions folder. This process is not currently automated.
 
 To explicitly rebuild the session snapshot html files, it is recommended that you
 first set the ``BST_SOURCE_CACHE`` environment variable to your source cache, this
diff --git a/doc/Makefile b/doc/Makefile
index 439c35358..3953fdd3c 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -51,6 +51,9 @@ BST2HTMLOPTS =
 ifneq ($(strip $(BST_FORCE_SESSION_REBUILD)),)
 BST2HTMLOPTS = --force
 endif
+ifneq ($(strip $(BST_DUMMY_REBUILD)),)
+BST2HTMLOPTS += --dummy
+endif
 
 # Help Python find buildstream and its plugins
 PYTHONPATH=$(CURDIR)/..:$(CURDIR)/../buildstream/plugins
diff --git a/doc/bst2html.py b/doc/bst2html.py
index a52dbefe2..ec5c2780b 100755
--- a/doc/bst2html.py
+++ b/doc/bst2html.py
@@ -329,7 +329,7 @@ def check_needs_build(basedir, filename, *, desc_mtime=None, force=None):
     return False
 
 
-def run_session(description, tempdir, source_cache, palette, config_file, force):
+def run_session(description, tempdir, source_cache, palette, config_file, force, dummy):
     desc_mtime = os.path.getmtime(description)
     desc = _yaml.load(description, shortname=os.path.basename(description))
     desc_dir = os.path.dirname(description)
@@ -404,7 +404,9 @@ def run_session(description, tempdir, source_cache, palette, config_file, force)
         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:
+        if dummy:
+            command_out = "Dummy Example Output\nThis doc build did not run example session."
+        elif command_fake_output is None:
             if is_shell:
                 command_out = run_shell_command(directory, command_str)
             else:
@@ -444,8 +446,10 @@ def run_session(description, tempdir, source_cache, palette, config_file, force)
 @click.option('--palette', '-p', default='tango',
               type=click.Choice(['solarized', 'solarized-xterm', 'tango', 'xterm', 'console']),
               help="Selects a palette for the output style")
+@click.option('--dummy', '-d', default=False,
+              is_flag=True, help="Create dummy output instead of running examples")
 @click.argument('description', type=click.Path(file_okay=True, dir_okay=False, readable=True))
-def run_bst(directory, force, source_cache, description, palette):
+def run_bst(directory, force, source_cache, description, palette, dummy):
     """Run a bst command and capture stdout/stderr in html
 
     This command normally takes a description yaml file, see the CONTRIBUTING
@@ -455,7 +459,7 @@ def run_bst(directory, force, source_cache, description, palette):
         source_cache = os.environ['BST_SOURCE_CACHE']
 
     with workdir(source_cache=source_cache) as (tempdir, config_file, source_cache):
-        run_session(description, tempdir, source_cache, palette, config_file, force)
+        run_session(description, tempdir, source_cache, palette, config_file, force, dummy)
 
     return 0