#2369: Reduce dependency on manually replacing primaite version across documentation

docs/conf.py

@@ -10,6 +10,7 @@ import datetime
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 import os
 import sys
+from typing import Any
 
 import furo  # noqa
 
@@ -63,3 +64,21 @@ html_theme = "furo"
 html_static_path = ["_static"]
 html_theme_options = {"globaltoc_collapse": True, "globaltoc_maxdepth": 2}
 html_copy_source = False
+
+
+def replace_token(app: Any, docname: Any, source: Any):
+    """Replaces a token from the list of tokens."""
+    result = source[0]
+    for key in app.config.tokens:
+        result = result.replace(key, app.config.tokens[key])
+    source[0] = result
+
+
+tokens = {"{VERSION}": release}  # Token VERSION is replaced by the value of the PrimAITE version in the version file
+"""Dict containing the tokens that need to be replaced in documentation."""
+
+
+def setup(app: Any):
+    """Custom setup for sphinx."""
+    app.add_config_value("tokens", {}, True)
+    app.connect("source-read", replace_token)

docs/source/example_notebooks.rst

@@ -17,12 +17,12 @@ Running Jupyter Notebooks
 .. code-block:: bash
     :caption: Unix
 
-    cd ~/primaite/PRIMAITE_VERSION_TOKEN
+    cd ~/primaite/{VERSION}
 
 .. code-block:: powershell
     :caption: Windows (Powershell)
 
-    cd ~\primaite\PRIMAITE_VERSION_TOKEN
+    cd ~\primaite\{VERSION}
 
 2. Run jupyter notebook
 

docs/source/getting_started.rst

@@ -38,12 +38,12 @@ Install PrimAITE
 .. code-block:: bash
     :caption: Unix
 
-    mkdir -p ~/primaite/3.0.0b6
+    mkdir -p ~/primaite/{VERSION}
 
 .. code-block:: powershell
     :caption: Windows (Powershell)
 
-    mkdir ~\primaite\3.0.0b6
+    mkdir ~\primaite\{VERSION}
 
 
 2. Navigate to the primaite directory and create a new python virtual environment (venv)
@@ -51,7 +51,7 @@ Install PrimAITE
 .. code-block:: bash
     :caption: Unix
 
-    cd ~/primaite/3.0.0b6
+    cd ~/primaite/{VERSION}
     python3 -m venv .venv
 
 .. code-block:: powershell

docs/source/primaite_session.rst

@@ -35,7 +35,7 @@ Outputs
 -------
 
 Running a session creates a session output directory in your user data folder. The filepath looks like this:
-``~/primaite/3.0.0b6/sessions/YYYY-MM-DD/HH-MM-SS/``. This folder contains the simulation sys logs generated by each node,
+``~/primaite/{VERSION}/sessions/YYYY-MM-DD/HH-MM-SS/``. This folder contains the simulation sys logs generated by each node,
 the saved agent checkpoints, and final model. The folder also contains a .json file for each episode step that
 contains the action, reward, and simulation state. These can be found in
-``~/primaite/3.0.0b6/sessions/YYYY-MM-DD/HH-MM-SS/simulation_output/episode_<n>/step_metadata/step_<n>.json``
+``~/primaite/{VERSION}/sessions/YYYY-MM-DD/HH-MM-SS/simulation_output/episode_<n>/step_metadata/step_<n>.json``