Use bullet point list for notes

Author: tsmbland

docs/generate_input_format_doc.py

@@ -63,7 +63,7 @@ def load_file(path: Path) -> File:
     name = f"{path.stem}.csv"
     desc = add_full_stop(data["description"])
     if note := data.get("notes", None):
-        note = add_full_stop(note)
+        note = format_notes(note)
     return File(name, desc, table, note)
 
 
@@ -91,6 +91,18 @@ def fields2table(fields: list[dict[str, str]]) -> tuple[str, str | None]:
     return table
 
 
+def format_notes(notes) -> str:
+    if isinstance(notes, list):
+        items = [add_full_stop(item) for item in notes]
+    elif isinstance(notes, str):
+        items = [add_full_stop(notes)]
+    else:
+        items = []
+    if not items:
+        return ""
+    return "\n".join(f"- {item}" for item in items)
+
+
 if __name__ == "__main__":
     output_path = _DOCS_DIR / "input_format.md"
     output_path.write_text(generate_markdown(), encoding="utf-8")

schemas/input/agent_commodity_portions.yaml

@@ -1,11 +1,13 @@
 description: |
   Portions of commodity demand for which agents are responsible.
 
-notes: |
-  If an entry is specified for one agent and commodity, there must be entries covering all milestone
-  years. For each agent listed in this file, the total portions for each region/commodity/year
-  combination must sum to one. In addition, there must be entries for every SVD and SED commodity
-  for all regions and milestone years.
+notes:
+  - If an entry is specified for one agent and commodity, there must be entries covering all
+    milestone years.
+  - For each agent listed in this file, the total portions for each region/commodity/year
+    combination must sum to one.
+  - In addition, there must be entries for every SVD and SED commodity for all regions and
+    milestone years.
 
 fields:
   - name: agent_id

schemas/input/agent_cost_limits.yaml

@@ -1,8 +1,8 @@
 description: |
   Limits on expenditure for agents.
 
-notes: |
-  If cost limits are provided for an agent, they must be present for all years.
+notes:
+  - If cost limits are provided for an agent, they must be present for all years.
 
 fields:
   - name: agent_id

schemas/input/agent_objectives.yaml

@@ -1,11 +1,12 @@
 description: |
   Describes the agents' objectives.
 
-notes: |
-  Every agent must have one objective for each milestone year. If the weighted sum decision rule is
-  in use, the `decision_weight` value must be provided, otherwise it must be omitted. If the lexico
-  decision rule is in use, the `decision_lexico_order` value must be provided, otherwise it must be
-  omitted.
+notes:
+  - Every agent must have one objective for each milestone year.
+  - If the weighted sum decision rule is in use, the `decision_weight` value must be provided,
+    otherwise it must be omitted.
+  - If the lexico decision rule is in use, the `decision_lexico_order` value must be provided,
+    otherwise it must be omitted.
 
 fields:
   - name: agent_id

schemas/input/agent_search_space.yaml

@@ -1,9 +1,9 @@
 description: |
   Defines the processes in which an agent will invest for given parameters.
 
-notes: |
-  If entries are missing for any combination of agent, commodity or milestone year, then it is
-  assumed that all processes can be considered in this case.
+notes:
+  - If entries are missing for any combination of agent, commodity or milestone year, then it is
+    assumed that all processes can be considered in this case.
 
 fields:
   - name: agent_id

schemas/input/commodities.yaml

@@ -1,10 +1,10 @@
 description: |
   Describes commodities in the system.
 
-notes: |
-  Every SED (supply equals demand) commodity must have both producer and consumer processes for
-  every region and milestone year. Every SVD (service demand) commodity must have a producer for
-  every region and milestone year.
+notes:
+  - Every SED (supply equals demand) commodity must have both producer and consumer processes for
+    every region and milestone year.
+  - Every SVD (service demand) commodity must have a producer for every region and milestone year.
 
 fields:
   - name: id

schemas/input/commodity_levies.yaml

@@ -1,9 +1,9 @@
 description: |
   Defines levies for commodities (or, if `value` is negative, incentives).
 
-notes: |
-  If an entry is included for a given combination of commodity and region, entries must be provided
-  covering all milestone years and time slices.
+notes:
+  - If an entry is included for a given combination of commodity and region, entries must be
+    provided covering all milestone years and time slices.
 
 fields:
   - name: commodity_id

schemas/input/demand.yaml

@@ -1,8 +1,9 @@
 description: |
   Specifies the demand for service demand commodities.
 
-notes: Every service demand commodity must have entries in this file covering every combination of
-  milestone year and region
+notes:
+  - Every service demand commodity must have entries in this file covering every combination of
+    milestone year and region
 
 fields:
   - name: commodity_id

schemas/input/demand_slicing.yaml

@@ -1,9 +1,10 @@
 description: |
   Specifies how demand is distributed throughout the year (i.e. for different milestones).
 
-notes: |
-  The user must provide entries covering every combination of service demand commodity, region and
-  time slice. For each combination, the sum of the fractions must equal one.
+notes:
+  - The user must provide entries covering every combination of service demand commodity, region
+    and time slice.
+  - For each combination, the sum of the fractions must equal one.
 
 fields:
   - name: commodity_id

schemas/input/process_availabilities.yaml

@@ -1,9 +1,9 @@
 description: |
   Defines how much of a process's capacity is available throughout the year.
 
-notes: |
-  Must be provided for every process.
-  Only one type of limit can be supplied for each combination of process/region/year/time slice.
+notes:
+  - Must be provided for every process.
+  - Only one type of limit can be supplied for each combination of process/region/year/time slice.
 
 fields:
   - name: process_id