Slightly reformat the input documentation

Author: tsmbland

.vscode/extensions.json

@@ -5,6 +5,8 @@
         "editorconfig.editorconfig",
         "esbenp.prettier-vscode",
         "davidanson.vscode-markdownlint",
-        "samuelcolvin.jinjahtml"
+        "samuelcolvin.jinjahtml",
+        "ms-python.python",
+        "charliermarsh.ruff"
     ]
 }

docs/generate_input_format_doc.py

@@ -21,18 +21,12 @@
 }
 
 
-@dataclass
-class Notes:
-    description: str | None
-    table: str | None
-
-
 @dataclass
 class File:
     name: str
     description: str
     table: str
-    notes: Notes | None
+    notes: str | None
 
 
 @dataclass
@@ -61,17 +55,16 @@ def load_file(path: Path) -> File:
         data = yaml.safe_load(f)
 
     try:
-        table, notes_table = fields2table(data["fields"])
+        table = fields2table(data["fields"])
     except KeyError:
         print(f"MISSING VALUE IN {path}")
         raise
 
     name = f"{path.stem}.csv"
-    title = add_full_stop(data["title"])
-    if desc := data.get("description", None):
-        desc = add_full_stop(desc)
-    notes = Notes(desc, notes_table) if desc or notes_table else None
-    return File(name, title, table, notes)
+    desc = add_full_stop(data["description"])
+    if note := data.get("notes", None):
+        note = add_full_stop(note)
+    return File(name, desc, table, note)
 
 
 def add_full_stop(s: str) -> str:
@@ -84,28 +77,18 @@ def add_full_stop(s: str) -> str:
 
 def fields2table(fields: list[dict[str, str]]) -> tuple[str, str | None]:
     data = []
-    notes = []
     for f in fields:
-        row = {"Field": f"`{f['name']}`", "Description": f["title"]}
-        data.append(row)
-
-        if desc := f.get("description", ""):
-            # MarkdownTable can't handle newlines, so replace with HTML equivalent
-            desc = desc.replace("\n\n", "<br /><br />").replace("\n", " ")
-            row = {"Field": f"`{f['name']}`", "Notes": desc}
-            notes.append(row)
-
-    data = [
-        {
+        # MarkdownTable can't handle newlines, so replace with HTML equivalent
+        desc = f.get("description", "")
+        desc = desc.replace("\n\n", "<br /><br />").replace("\n", " ")
+        row = {
             "Field": f"`{f['name']}`",
             "Description": f["title"],
+            "Notes": desc,
         }
-        for f in fields
-    ]
-
+        data.append(row)
     table = str(MarkdownTable.from_dicts(data))
-    notes_table = str(MarkdownTable.from_dicts(notes)) if notes else None
-    return table, notes_table
+    return table
 
 
 if __name__ == "__main__":

docs/input_format.md.jinja

@@ -26,10 +26,9 @@ This file contains information about the input file format for MUSE 2.0.
     (such as a requirement that the value is >=0 etc.). -#}
 {%- if file.notes %}
 #### Notes
-{% if file.notes.description %}
-{{ file.notes.description }}{% endif %}
-{% if file.notes.table %}
-{{ file.notes.table }}{% endif -%}
+{{ file.notes }}
 {%- endif %}
+
 {% endfor -%}
+
 {% endfor %}

schemas/input/agent_commodity_portions.yaml

@@ -1,7 +1,7 @@
-title: Commodity demand portions for agents
 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

schemas/input/agent_cost_limits.yaml

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

schemas/input/agent_objectives.yaml

@@ -1,7 +1,7 @@
-title: Agent objectives
 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

schemas/input/agent_search_space.yaml

@@ -1,7 +1,7 @@
-title: Agent search space
 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.
 

schemas/input/agents.yaml

@@ -1,4 +1,3 @@
-title: Main agents file
 description: Describes agents in the system
 fields:
   - name: id

schemas/input/assets.yaml

@@ -1,4 +1,3 @@
-title: Main assets file
 description: Defines assets in the system
 
 fields:

schemas/input/commodities.yaml

@@ -1,5 +1,7 @@
-title: Main commodities file
 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.