Repository: conbench/conbench (language: python)

Issue:
Populate ClusterCreate docs
Documentation here https://conbench.ursa.dev/api/docs/#/ under `ClusterCreate` has no metadata populated yet:

<img width="467" alt="image" src="https://user-images.githubusercontent.com/18472598/203437879-c0f41b4b-0a69-4b8e-b804-1c5e97c16d78.png">

These fields describe clusters along these lines (though you might need to edit these slightly to fit with the style of the other API docs and to shorten them a bit):
- `info`: Information on the cluster (e.g. hosts, nodes or number of workers) that has been configured to run a set of benchmarks. This information should include all cluster configuration details that we suspect might impact benchmark performance (types of hardware for the nodes, number of nodes, etc). This mirrors the tags in the Machine Info. This information will be used to separate the results from the same benchmark run on different sets of hardware.
- `name`: A descriptive name of a cluster. This should be short, but distinctive — it is displayed in the conbench web app UI
- `optional_info`: Any additional optional information about the cluster. This is a good place to put configuration details that we don't expect to impact benchmark performance (e.g. region, settings like logging type, etc.). This information should be about the cluster itself that is the same across benchmarks run on the same cluster (e.g. if you have information that is unique to each benchmark, that should go in `optional_benchmark_info`) 

This metadata can be added here: 
https://github.com/conbench/conbench/blob/093e61385f9716b801ec03a773cfe281c43ce4c8/conbench/entities/hardware.py#L190-L193

Much like they are populated here:
https://github.com/conbench/conbench/blob/fdb30f2934481989e981c49837506c0622d6bb3a/conbench/entities/run.py#L217-L222





Discussion / hints:

Fix patch:
diff --git a/conbench/entities/hardware.py b/conbench/entities/hardware.py
index 39c66d8d3..3482f0d9b 100644
--- a/conbench/entities/hardware.py
+++ b/conbench/entities/hardware.py
@@ -188,9 +188,27 @@ class MachineCreate(marshmallow.Schema):
 
 
 class ClusterCreate(marshmallow.Schema):
-    name = marshmallow.fields.String(required=True)
-    info = marshmallow.fields.Dict(required=True)
-    optional_info = marshmallow.fields.Dict(required=True)
+    name = marshmallow.fields.String(
+        required=True,
+        metadata={
+            "description": "Distinct name of the cluster, to be displayed on the web UI."
+        },
+    )
+    info = marshmallow.fields.Dict(
+        required=True,
+        metadata={
+            "description": "Information related to cluster (e.g. `hosts`, `nodes` or `number of workers`) "
+            "configured to run a set of benchmarks. Used to differentiate between similar "
+            "benchmark runs performed on different sets of hardware"
+        },
+    )
+    optional_info = marshmallow.fields.Dict(
+        required=True,
+        metadata={
+            "description": "Additional optional information about the cluster, which is not likely to impact the "
+            "benchmark performance (e.g. region, settings like logging type, etc)."
+        },
+    )
 
 
 class MachineSchema:


Test patch:
diff --git a/conbench/tests/api/_expected_docs.py b/conbench/tests/api/_expected_docs.py
index becec63a8..bed25f2fa 100644
--- a/conbench/tests/api/_expected_docs.py
+++ b/conbench/tests/api/_expected_docs.py
@@ -1067,9 +1067,18 @@
             },
             "ClusterCreate": {
                 "properties": {
-                    "info": {"type": "object"},
-                    "name": {"type": "string"},
-                    "optional_info": {"type": "object"},
+                    "info": {
+                        "description": "Information related to cluster (e.g. `hosts`, `nodes` or `number of workers`) configured to run a set of benchmarks. Used to differentiate between similar benchmark runs performed on different sets of hardware",
+                        "type": "object",
+                    },
+                    "name": {
+                        "description": "Distinct name of the cluster, to be displayed on the web UI.",
+                        "type": "string",
+                    },
+                    "optional_info": {
+                        "description": "Additional optional information about the cluster, which is not likely to impact the benchmark performance (e.g. region, settings like logging type, etc).",
+                        "type": "object",
+                    },
                 },
                 "required": ["info", "name", "optional_info"],
                 "type": "object",