doc: Improve the new console output html generator

Before we were creating one description file for each output,
making it easier to declare a make rule for it - but the result
was that we would have to build things more and it takes a
long time.

Instead, now we have session files which describe a series of commands
to run in a session, and each command optionally produces an output file.

1 files changed, 31 insertions, 13 deletions

diff --git a/HACKING.rst b/HACKING.rst
index 8ef82244f..d326a7b35 100644
--- a/HACKING.rst
+++ b/HACKING.rst
@@ -269,9 +269,9 @@ you can view in your browser locally to test.
 
 Regenerating session html
 '''''''''''''''''''''''''
-The documentation build will only build the session files if they
-are not yet built, and we revision the session files to make it easier
-for developers to try documentation changes.
+The documentation build will only build the session files if explicitly
+asked to. We revision the generated session html files in order to reduce
+the burden on documentation contributors.
 
 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
@@ -279,10 +279,9 @@ will make the docs build reuse already downloaded sources::
 
   export BST_SOURCE_CACHE=~/.cache/buildstream/sources
 
-To force rebuild, simply run the following::
+To force build the session html, simply run the following::
 
-  make -C doc clean
-  make -C doc
+  make -C doc sessions
 
 
 Man pages
@@ -375,17 +374,36 @@ included in the reStructuredText documentation at any time with::
   .. raw:: html
      :file: sessions/${example}.html
 
-The ``.run`` file format is just another YAML dictionary with a few options:
+The ``.run`` file format is just another YAML dictionary which consists of a
+``commands`` list, instructing the program what to do command by command.
+
+Each *command* is a dictionary, the members of which are listed here:
+
+* ``directory``: The input file relative project directory
+
+* ``output``: The input file relative output html file to generate (optional)
+
+* ``command``: The command to run, without the leading ``bst``
+
+When adding a new ``.run`` file, one should normally also commit the new
+resulting generated ``.html`` file(s) at the same time, this ensures that
+other developers do not need to regenerate them locally in order to build
+the docs.
+
+**Example**:
 
-* ``directory``: The project directory to run commands on, relative to the ``.run`` file.
+.. code:: yaml
 
-* ``prepare-commands``: A list of command strings which should be run first
+   commands:
 
-* ``command``: The command to capture the output of
+   # Make it fetch first
+   - directory: ../examples/foo
+     command: fetch hello.bst
 
-When adding a new ``.run`` file, one should normally also commit a new
-generated ``.html`` file at the same time, this ensures that other developers
-do not need to regenerate them locally in order to build the docs.
+   # Capture a build output
+   - directory: ../examples/foo
+     output: ../source/sessions/foo-build.html
+     command: build hello.bst
 
 
 Testing BuildStream