From 1d09f0791a0dc4c89a8faafa8f545e348cf641e3 Mon Sep 17 00:00:00 2001
From: Czar Echavez <Czar.Echavez@envitia.com>
Date: Thu, 14 Mar 2024 23:17:34 +0000
Subject: [PATCH] #2369: Reduce dependency on manually replacing primaite
 version across documentation

---
 docs/conf.py                      | 19 +++++++++++++++++++
 docs/source/example_notebooks.rst |  4 ++--
 docs/source/getting_started.rst   |  6 +++---
 docs/source/primaite_session.rst  |  4 ++--
 4 files changed, 26 insertions(+), 7 deletions(-)

diff --git a/docs/conf.py b/docs/conf.py
index d246afe5..a666e460 100644
--- a/docs/conf.py
+++ b/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)
diff --git a/docs/source/example_notebooks.rst b/docs/source/example_notebooks.rst
index 9fb5cc9e..1ea94249 100644
--- a/docs/source/example_notebooks.rst
+++ b/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
 
diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst
index c1559168..7a23e4f8 100644
--- a/docs/source/getting_started.rst
+++ b/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
diff --git a/docs/source/primaite_session.rst b/docs/source/primaite_session.rst
index b02e015e..d0caeaad 100644
--- a/docs/source/primaite_session.rst
+++ b/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``