From fc5ff8d0722d0e3214685329570d83e67d6573e8 Mon Sep 17 00:00:00 2001
From: Chell <im.chell@outlook.com>
Date: Thu, 2 May 2024 21:48:21 +0200
Subject: [PATCH] Refactor README.md to include architectural overview, getting
 started guide, and plugin execution order in Midori

---
 README.md                         | 19 +++++++++++++++++--
 midori/plugins/example_plugins.py |  4 ++--
 midori/plugins/helpers.py         |  4 ++--
 3 files changed, 21 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index 542c092..c13c1cb 100644
--- a/README.md
+++ b/README.md
@@ -62,10 +62,12 @@ To help you better understand this, the green boxes in the following illustratio
 
 Clearly there are 4 parameters that invoke the plugins to be run at different stages of the experiment. The 4 parameters are lists of **class definitions** (not instances).
 
+Plugins defined in `before_experiment_plugins`, `setup_plugins`, `end_trial_plugins`, `end_experiment_plugins` are run in the order. `[A, B, C]` means `A` is run first, then `B`, and finally `C`, with the output of `A` passed to `B` and the output of `B` passed to `C`.
+
 The way we define these plugins is by inheriting from the `PluginHelper` class and overriding the `action` method. Here is an example:
 
 ```python
-from .helpers import PluginHelper
+from midori.plugins.helpers import PluginHelper
 
 class SkaffoldSetup(PluginHelper):
     def action(self) -> str:
@@ -82,6 +84,10 @@ class CheckRam(PluginHelper):
 - `self.previous_output`: The output of the previous plugin. For example, if `end_trial_plugins = [CheckRam, NewPlugin]`, where `CheckRam` is the plugin shown above, the `NewPlugin` will have access to the output of `CheckRam` in `self.previous_output` as `MemTotal:       900000000 kB`.
 - `self.treatment`: The treatment of the current trial.
 
+### Escape Hatch
+
+- If you really want access to the SSH client in the plugin `action()` method, you can access it via `self._ssh` (it's `paramiko.SSHClient`). Most of the time it's not necessary to use it. The only reason I kept it is to make my old plugins work with the new version of Midori.
+
 ## 🚧 Development and Contribution
 
 1. Install [poetry](https://python-poetry.org/docs/#installation).
@@ -90,6 +96,15 @@ class CheckRam(PluginHelper):
 4. Run `pre-commit install` to install [pre-commit](https://pre-commit.com/) hooks.
 5. Develop on `dev` branch and create a pull request to `dev` branch.
 
-```
+## 📝 Citation
 
 ```
+@misc{midori,
+  author = {Xingwen Xiao},
+  title = {Midori},
+  year = {2024},
+  publisher = {GitHub},
+  journal = {GitHub repository},
+  howpublished = {\url{https://github.com/imchell/midori}},
+}
+```
diff --git a/midori/plugins/example_plugins.py b/midori/plugins/example_plugins.py
index 81998cd..d40c62a 100644
--- a/midori/plugins/example_plugins.py
+++ b/midori/plugins/example_plugins.py
@@ -9,7 +9,7 @@ def action(self) -> str:
 class EnergyDataCollection(PluginHelper):
     def action(self) -> None:
         energy_collector: PodHelper = PodHelper(
-            self.ssh, "prometheus-server", "default"
+            self._ssh, "prometheus-server", "default"
         )
         energy_node_save_path = f"~/research/results/{self.treatment}/energy.json"
         energy_collector.execute_query_in_pod(
@@ -21,5 +21,5 @@ def action(self) -> None:
 class LoadTestingDataCollection(PluginHelper):
     def action(self) -> None:
         treatment_node_save_path = f"~/research/results/{self.treatment}"
-        pft: PodHelper = PodHelper(self.ssh, "loadgenerator", "default")
+        pft: PodHelper = PodHelper(self._ssh, "loadgenerator", "default")
         pft.transfer_file_from_pod("/loadgen", treatment_node_save_path)
diff --git a/midori/plugins/helpers.py b/midori/plugins/helpers.py
index 3b28218..40cacd6 100644
--- a/midori/plugins/helpers.py
+++ b/midori/plugins/helpers.py
@@ -12,7 +12,7 @@ def __init__(
         treatment: str,
         previous_output: Optional[str] = None,
     ):
-        self.ssh = ssh
+        self._ssh = ssh
         self.subject_path = subject_path
         self.previous_output = previous_output
         self.treatment = treatment
@@ -21,7 +21,7 @@ def __init__(
     def execute(self) -> Optional[str]:
         command = self.action()
         if command:
-            return execute(command, self.ssh)
+            return execute(command, self._ssh)
         return None
 
     def action(self) -> Optional[str]: