Create script to automatically generate a settings menu help file

Documentation/Development.md

@@ -20,54 +20,71 @@ Use the following steps to set up a build environment for IronOS on the command
 
 1. [Follow steps 1 – 3 here to install the toolchain](https://github.com/glegrain/STM32-with-macOS#0---installing-the-toolchain) needed to compile for STM32 microcontrollers.
 2. Install `python`:
+
 ```
 brew install python
 ```
+
 3. (Optional) Update `pip` so it doesn't warn you about being out-of-date:
+
 ```
 python3 -m pip install --upgrade pip
 ```
+
 4. Change to the `source` directory:
+
 ```
 cd source
 ```
+
 5. Create a Python virtual environment for IronOS named `ironos-venv` to keep your Python installation clean:
+
 ```
 python3 -m venv ironos-venv
 ```
+
 6. Activate the Python virtual environment:
+
 ```
 source ironos-venv/bin/activate
 ```
+
 7. Install the dependencies required to run `make-translation.py`:
+
 ```
 pip install bdflib
 ```
+
 8. All done! See some examples below for how you can build your own IronOS.
 
 ### Examples
 
 To build a single language Simplified Chinese firmware for the TS80P with 8 simultaneous jobs:
+
 ```
 make -j8 model=TS80P firmware-ZH_CN
 ```
 
 To build a European multi-language firmware for the Pinecil with as many simultaneous jobs as there are logical processors on Linux:
+
 ```
 make -j$(nproc) model=Pinecil firmware-multi_European
 ```
 
 To build a Cyrillic compressed multi-language firmware for the Pinecil with as many simultaneous jobs as there are logical processors on macOS:
+
 ```
 make -j$(sysctl -n hw.logicalcpu) model=Pinecil firmware-multi_compressed_Bulgarian+Russian+Serbian+Ukrainian
 ```
 
 To build a custom multi-language firmware including English and Simplified Chinese for the TS80:
+
 ```
 make -j8 model=TS80 custom_multi_langs="EN ZH_CN" firmware-multi_Custom
 ```
 
 To build a custom compressed multi-language firmware including German, Spanish, and French for the TS100 (note if `model` is unspecified, it will default to `TS100`):
+
 ```
 make -j8 custom_multi_langs="DE ES FR" firmware-multi_compressed_Custom
 ```
@@ -77,6 +94,7 @@ To build a release instead, run the `build.sh` script. This will update translat
 ## Updating languages
 
 To update the language translation files and their associated font maps, execute the `make_translation.py` code from the `Translations` directory.
+If you edit the translation definitions or the english translation, please also run `gen_menu_docs.py` to update the settings menu documentation automatically.
 
 ## Building Pinecil
 

Translations/gen_menu_docs.py

@@ -0,0 +1,112 @@
+#!/usr/bin/env python3
+
+import argparse
+import functools
+import hashlib
+import json
+import logging
+import os
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Dict, List
+
+logging.basicConfig(stream=sys.stdout, level=logging.DEBUG)
+
+HERE = Path(__file__).resolve().parent
+TRANSLATION_DEFS_PATH = os.path.join(HERE, "translations_def.js")
+ENGLISH_TRANSLATION_PATH = os.path.join(HERE, "translation_EN.json")
+MENU_DOCS_FILE_PATH = os.path.join(HERE.parent, "Documentation/Settings.md")
+
+# Loading a single JSON file
+def load_json(filename: str, skip_first_line: bool) -> dict:
+    with open(filename) as f:
+        if skip_first_line:
+            f.readline()
+        return json.loads(f.read())
+
+
+def write_header(filep):
+    """
+    Writes the markdown constant header area out
+    """
+    constant_header = """<!-- This is an automatically generated file. DO NOT EDIT. Edit gen_menu_docs.py instead -->
+
+# IronOS Settings Menu
+
+The below breaks down the menu's and what each setting means.
+    """
+    filep.write(constant_header)
+
+
+def write_menu_categories(filep, defs, translation_data):
+    """
+    Writes the menu categories section out
+    """
+    menu_cat_pretense = """
+## Menu Categories
+
+In the menu there are a few main categories that are used to keep the list manageable.
+"""
+    filep.write(menu_cat_pretense)
+    for menu in defs.get("menuGroups", {}):
+        menu_id = menu.get("id", "")
+        entry = translation_data.get("menuGroups", {}).get(menu_id, "")
+        name = " ".join(entry.get("text2", []))
+        desc = menu.get("description", "")
+        section = f"""
+### Category: {name}
+
+{desc}
+"""
+        filep.write(section)
+
+
+def write_menu_entries(filep, defs, translation_data):
+    """
+    Writes the menu entries section out
+    """
+    menu_entries_pretense = """
+## Settings
+
+These are all off the settings possible in the menu. 
+Not all settings are visible for all devices.
+For example, the TS100 does not have USB-PD settings.
+
+When using the device, if unsure you can pause (press nothing) on a setting and after a short delay help text will scroll across the screen.
+This is the "on device help text".
+"""
+    filep.write(menu_entries_pretense)
+    for menu in defs.get("menuOptions", {}):
+        menu_id = menu.get("id", "")
+        entry = translation_data.get("menuOptions", {}).get(menu_id, "")
+        name = " ".join(entry.get("text2", []))
+        desc = menu.get("description", "")
+        on_device_desc = entry.get("desc", "")
+        section = f"""
+### Setting: {name}
+
+{desc}
+
+On device help text:
+
+{on_device_desc}
+"""
+        filep.write(section)
+
+
+def main() -> None:
+    json_dir = HERE
+    print(json_dir)
+    logging.info("Loading translation definitions")
+    defs = load_json(TRANSLATION_DEFS_PATH, True)
+    eng_translation = load_json(ENGLISH_TRANSLATION_PATH, False)
+    with open(MENU_DOCS_FILE_PATH, "w") as outputf:
+        write_header(outputf)
+        write_menu_categories(outputf, defs, eng_translation)
+        write_menu_entries(outputf, defs, eng_translation)
+    logging.info("Done")
+
+
+if __name__ == "__main__":
+    main()