Improve docs, including adding a gallery of the TUI

EdmundGoodman · Apr 15, 2024 · 9e3a2da · 9e3a2da
1 parent 61df9fe
commit 9e3a2da
Show file tree

Hide file tree

Showing 16 changed files with 105 additions and 5 deletions.
diff --git a/docs/gallery.md b/docs/gallery.md
@@ -0,0 +1,70 @@
+---
+hide:
+  - navigation
+---
+
+# Gallery
+
+This page shows a gallery of the capabilities of the HPC MultiBench tool.
+
+## Viewing run configurations
+
+<figure markdown="span">
+  ![Viewing run configurations](./images/hpc-multibench-run-configurations.png){ loading=lazy }
+  <figcaption>A screenshot of the TUI viewing a run configuration, including the instantiation of variables and the Slurm sbatch file to run.</figcaption>
+</figure>
+
+## Viewing aggregated metrics
+
+<figure markdown="span">
+  ![Viewing aggregated metrics](./images/hpc-multibench-aggregated-metrics.png){ loading=lazy }
+  <figcaption>A screenshot of the TUI viewing the metric results extracted from and aggregated across a set of runs defined in the YAML file.</figcaption>
+</figure>
+
+## Dispatching runs
+
+<figure markdown="span">
+  ![Viewing aggregated metrics](./images/hpc-multibench-dispatch-runs.png){ loading=lazy }
+  <figcaption>A screenshot of the TUI showing a modal dialog as it spawns Slurm jobs after  the "Run Test Plan" button is pressed.</figcaption>
+</figure>
+
+## Line plots
+
+<figure markdown="span">
+  ![Plotext line plots](./images/hpc-multibench-line-plotext.png){ loading=lazy }
+  <figcaption>A screenshot of a a line plot of the metrics rendered entirely in the terminal.</figcaption>
+</figure>
+
+<figure markdown="span">
+  ![Plotext line plots](./images/hpc-multibench-line-plotext-2.png){ loading=lazy }
+  <figcaption>A screenshot of a a line plot of the metrics rendered entirely in the terminal.</figcaption>
+</figure>
+
+<figure markdown="span">
+  ![Matplotlib line plots](./images/hpc-multibench-line-matplotlib.png){ loading=lazy }
+  <figcaption>A screenshot of a Matplotlib window spawned by the TUI displaying a line plot including error bars of the metrics.</figcaption>
+</figure>
+
+## Bar plots
+
+<figure markdown="span">
+  ![Plotext bar plots](./images/hpc-multibench-bar-plotext.png){ loading=lazy }
+  <figcaption>A screenshot of a a bar plot of the metrics rendered entirely in the terminal.</figcaption>
+</figure>
+
+<figure markdown="span">
+  ![Matplotlib bar plots](./images/hpc-multibench-bar-matplotlib.png){ loading=lazy }
+  <figcaption>A screenshot of a Matplotlib window spawned by the TUI displaying a bar plot including error bars of the metrics.</figcaption>
+</figure>
+
+## Roofline plots
+
+<figure markdown="span">
+  ![Plotext roofline plots](./images/hpc-multibench-roofline-plotext.png){ loading=lazy }
+  <figcaption>A screenshot of a a roofline plot of the metrics rendered entirely in the terminal.</figcaption>
+</figure>
+
+<figure markdown="span">
+  ![Matplotlib roofline plots](./images/hpc-multibench-roofline-matplotlib.png){ loading=lazy }
+  <figcaption>A screenshot of a Matplotlib window spawned by the TUI displaying a roofline plot including error bars of the metrics.</figcaption>
+</figure>
diff --git a/docs/images/hpc-multibench-aggregated-metrics.png b/docs/images/hpc-multibench-aggregated-metrics.png
diff --git a/docs/images/hpc-multibench-bar-matplotlib.png b/docs/images/hpc-multibench-bar-matplotlib.png
diff --git a/docs/images/hpc-multibench-bar-plotext.png b/docs/images/hpc-multibench-bar-plotext.png
diff --git a/docs/images/hpc-multibench-dispatch-runs.png b/docs/images/hpc-multibench-dispatch-runs.png
diff --git a/docs/images/hpc-multibench-line-matplotlib.png b/docs/images/hpc-multibench-line-matplotlib.png
diff --git a/docs/images/hpc-multibench-line-plotext-2.png b/docs/images/hpc-multibench-line-plotext-2.png
diff --git a/docs/images/hpc-multibench-line-plotext.png b/docs/images/hpc-multibench-line-plotext.png
diff --git a/docs/images/hpc-multibench-roofline-matplotlib.png b/docs/images/hpc-multibench-roofline-matplotlib.png
diff --git a/docs/images/hpc-multibench-roofline-plotext.png b/docs/images/hpc-multibench-roofline-plotext.png
diff --git a/docs/images/hpc-multibench-run-configurations.png b/docs/images/hpc-multibench-run-configurations.png
diff --git a/docs/index.md b/docs/index.md
@@ -15,7 +15,8 @@ HPC batch compute jobs via Slurm from a convenient YAML format.
 - [x] Define experiments from a convenient YAML file
 - [x] Support for zero effort re-runs of experiments, with aggregation for
       uncertainty calculations and error bars
-- [x] Simple metric extraction and graph plotting from run results
+- [x] Simple metric extraction and graph plotting from run results, including
+      line, bar and roofline plots
 - [x] Rendered entirely in the terminal -- including graph plotting capabilities;
       no need to set up X-forwarding!
 

diff --git a/docs/manual.md b/docs/manual.md
@@ -5,6 +5,11 @@ hide:
 
 # Manual
 
+When the `hpc-multibench` tool and its subcommands are invoked with the `-h` or
+`--help` flags, the following help pages are displayed.
+
+## Top-level help page
+
 ```
 usage: __main__.py [-h] -y YAML_PATH [-o OUTPUTS_DIRECTORY] {record,interactive,report} ...
 
@@ -24,7 +29,7 @@ options:
                         the path to the configuration YAML file
 ```
 
-## `record` subcommand
+## `record` subcommand help page
 
 ```
 usage: __main__.py record [-h] [-d] [-w] [-nc]
@@ -36,7 +41,7 @@ options:
   -nc, --no-clobber  don't delete any previous run results of the test benches
 ```
 
-## `report` subcommand
+## `report` subcommand help page
 
 ```
 usage: __main__.py report [-h]
@@ -45,7 +50,7 @@ options:
   -h, --help  show this help message and exit
 ```
 
-## `interactive` subcommand
+## `interactive` subcommand help page
 
 ```
 usage: __main__.py interactive [-h] [-nc]

diff --git a/docs/quickstart.md b/docs/quickstart.md
@@ -14,7 +14,7 @@ To install the tool, clone and navigate to the repository, then use poetry to
 create a virtual environment as follows:
 
 ```bash
-git clone https://github.com/EdmundGoodman/hpc-multibench
+git clone --recurse-submodules -j8 https://github.com/EdmundGoodman/hpc-multibench
 cd hpc-multibench
 poetry install --without docs,test,dev
 ```

diff --git a/docs/yaml_schema.md b/docs/yaml_schema.md
@@ -0,0 +1,20 @@
+---
+hide:
+  - navigation
+---
+
+# YAML Schema
+
+## Run Configurations
+
+## Test Benches
+
+### Reruns
+
+### Matrix
+
+### Analysis
+
+#### Metrics
+
+#### Plotting
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -16,12 +16,14 @@ nav:
   - Home: index.md
   - Quick start: quickstart.md
   - Manual: manual.md
+  - YAML schema: yaml_schema.md
   - Reference:
       - Main: reference/main.md
       - YAML model: reference/yaml_model.md
       - Test bench: reference/test_bench.md
       - Run configuration: reference/run_configuration.md
       - Roofline model: reference/roofline_model.md
+  - Gallery: gallery.md
   - Contributing: contributing.md
 
 theme:
@@ -57,7 +59,9 @@ markdown_extensions:
   # Inbuilt extensions
   # https://python-markdown.github.io/extensions/
   - admonition
+  - attr_list
   - footnotes
+  - md_in_html
   - meta
   - sane_lists
   - smarty