Improve documentation, including splitting out reference section

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

Hide file tree

Showing 7 changed files with 29 additions and 18 deletions.
diff --git a/docs/quickstart.md b/docs/quickstart.md
@@ -10,9 +10,12 @@ command line.
 
 ## Installation
 
-To install the tool, use poetry to create a virtual environment as follows:
+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
+cd hpc-multibench
 poetry install --without docs,test,dev
 ```
 
@@ -22,7 +25,7 @@ Using the `parallelism` test plan in the `hpccg-rs-kudu-results` submodule as
 an example, we can interactively view the data as follows:
 
 ```bash
-poetry run python3 -m hpc_multibench \
+poetry run hpc-multibench \
     -y generated_results/hpccg-rs-kudu-results/_test_plans/parallelism.yaml \
     -o generated_results/hpccg-rs-kudu-results/ \
     interactive
@@ -42,7 +45,7 @@ mode.
 On a system with Slurm installed, runs can be dispatched as follows:
 
 ```bash
-poetry run python3 -m hpc_multibench \
+poetry run hpc-multibench \
     -y generated_results/hpccg-rs-kudu-results/_test_plans/parallelism.yaml \
     record
 ```
@@ -55,7 +58,7 @@ files to a directory called `results/` at the root of the repository.
 Run results can also be viewed non-interactively as follows:
 
 ```bash
-poetry run python3 -m hpc_multibench \
+poetry run hpc-multibench \
     -y generated_results/hpccg-rs-kudu-results/_test_plans/parallelism.yaml \
     -o generated_results/hpccg-rs-kudu-results/ \
     report

diff --git a/docs/reference/main.md b/docs/reference/main.md
@@ -3,13 +3,3 @@
 ::: hpc_multibench.main
 
 ::: hpc_multibench.test_plan
-
-::: hpc_multibench.test_bench
-
-::: hpc_multibench.run_configuration
-
-::: hpc_multibench.yaml_model
-
-::: hpc_multibench.roofline_model
-
-::: hpc_multibench.uncertainties
diff --git a/docs/reference/roofline_model.md b/docs/reference/roofline_model.md
@@ -0,0 +1,3 @@
+# Reference
+
+::: hpc_multibench.roofline_model
diff --git a/docs/reference/run_configuration.md b/docs/reference/run_configuration.md
@@ -0,0 +1,3 @@
+# Reference
+
+::: hpc_multibench.run_configuration
diff --git a/docs/reference/test_bench.md b/docs/reference/test_bench.md
@@ -0,0 +1,5 @@
+# Reference
+
+::: hpc_multibench.test_bench
+
+::: hpc_multibench.uncertainties
diff --git a/docs/reference/yaml_model.md b/docs/reference/yaml_model.md
@@ -0,0 +1,3 @@
+# Reference
+
+::: hpc_multibench.yaml_model
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -14,10 +14,14 @@ use_directory_urls: false
 
 nav:
   - Home: index.md
-  - Quickstart: quickstart.md
+  - Quick start: quickstart.md
   - Manual: manual.md
   - Reference:
-      - Tool: reference/main.md
+      - 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
   - Contributing: contributing.md
 
 theme:
@@ -70,8 +74,8 @@ markdown_extensions:
   - pymdownx.caret
   - pymdownx.details
   - pymdownx.emoji:
-      emoji_index: !!python/name:materialx.emoji.twemoji
-      emoji_generator: !!python/name:materialx.emoji.to_svg
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
   - pymdownx.highlight:
       linenums: true
       anchor_linenums: true
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		# Reference

		::: hpc_multibench.run_configuration