diff --git a/Documentation/Development.md b/Documentation/Development.md index 65e50955..1a60f781 100644 --- a/Documentation/Development.md +++ b/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: +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: +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: +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: +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`): +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 diff --git a/Translations/gen_menu_docs.py b/Translations/gen_menu_docs.py new file mode 100755 index 00000000..c0593da2 --- /dev/null +++ b/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 = """ + +# 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()