Merge pull request #564 from zapta/develop

Color themes, command shortcusts, and cli documentation.
FPGAwars · Feb 2, 2025 · 1751e54 · 1751e54
2 parents f4a8ac2 + 2c0402c
commit 1751e54
Show file tree

Hide file tree

Showing 66 changed files with 1,072 additions and 633 deletions.
diff --git a/.vscode/settings.json b/.vscode/settings.json
@@ -44,12 +44,14 @@
         "cwarning",
         "cwidth",
         "dblite",
+        "debugpy",
         "Deconflicting",
         "determinisitc",
         "devides",
         "devmgmt",
         "dialout",
         "dumpfile",
+        "EMPH",
         "envlist",
         "EXMPLS",
         "FGPA",

diff --git a/COMMANDS.md b/COMMANDS.md
@@ -5,6 +5,7 @@
   * [apio clean](#apio-clean) - Delete the apio generated files.
   * [apio create](#apio-create) - Create an apio.ini project file.
   * [apio docs](#apio-docs) - Read apio documentations.
+    * [apio docs cli](#apio-docs-cli) - Apio's command line conventions.'
     * [apio docs options](#apio-docs-options) - Apio.ini options documentation.
     * [apio docs resources](#apio-docs-resources) - Information about online resources.
   * [apio drivers](#apio-drivers) - Manage the operating system drivers.
@@ -32,8 +33,6 @@
     * [apio packages list](#apio-packages-list) - List apio packages.
     * [apio packages uninstall](#apio-packages-uninstall) - Uninstall apio packages.
   * [apio preferences](#apio-preferences) - Manage the apio user preferences.
-    * [apio preferences list](#apio-preferences-list) - List the apio user preferences.
-    * [apio preferences set](#apio-preferences-set) - Set the apio user preferences.
   * [apio raw](#apio-raw) - Execute commands directly from the Apio packages.
   * [apio report](#apio-report) - Report design utilization and timing.
   * [apio sim](#apio-sim) - Simulate a testbench with graphic results.
@@ -214,19 +213,37 @@ Options:
 Usage: apio docs [OPTIONS] COMMAND [ARGS]...
 
   The command group 'apio docs' contains subcommands that provides
-  various apio documentation and references to online resources.
+  various apio documentation and references information.
 
 Options:
   -h, --help  Show this message and exit.
 
 Subcommands:
+  apio docs cli        Apio's command line conventions.'
   apio docs options    Apio.ini options documentation.
   apio docs resources  Information about online resources.
 
 ```
 
 <br>
 
+### apio docs cli
+
+```
+Usage: apio docs cli [OPTIONS]
+
+  The command 'apio docs cli' provides information the Apio's command
+  line conventions and features.
+  Examples:
+    apio docs cli        # Shoe the cli documentation text.
+
+Options:
+  -h, --help  Show this message and exit.
+
+```
+
+<br>
+
 ### apio docs options
 
 ```
@@ -750,6 +767,7 @@ Usage: apio packages install [OPTIONS] PACKAGE
 
   Examples:
     apio packages install                   # Install missing packages.
+    apio pack inst                          # Same, with shortcuts
     apio packages install --force           # Reinstall all packages.
     apio packages install oss-cad-suite     # Install package.
     apio packages install examples@0.0.32   # Install a specific
@@ -811,63 +829,25 @@ Options:
 ### apio preferences
 
 ```
-Usage: apio preferences [OPTIONS] COMMAND [ARGS]...
-
-  The command group 'apio preferences' contains subcommands to manage
-  the apio user preferences. These are user configurations that affect
-  all the apio projects that use the same apio home directory (e.g.
-  '~/.apio').
-
-  The user preference is not part of any apio project and typically are
-  not shared when multiple user collaborate on the same project.
-
-Options:
-  -h, --help  Show this message and exit.
-
-Subcommands:
-  apio preferences list  List the apio user preferences.
-  apio preferences set   Set the apio user preferences.
-
-```
-
-<br>
-
-### apio preferences list
-
-```
-Usage: apio preferences list [OPTIONS]
-
-  The command 'apio preferences list' lists the current user
-  preferences.
-
-  Examples:
-    apio preferences list  # List the user preferences.
-
-Options:
-  -h, --help  Show this message and exit.
-
-```
-
-<br>
-
-### apio preferences set
-
-```
-Usage: apio preferences set [OPTIONS]
+Usage: apio preferences [OPTIONS]
 
-  The command 'apio preferences set' allows to set the supported user
-  preferences.
+  The command 'apio preferences' allows to view and manage the setting
+  of the apio's user's preferences. These settings are stored in the
+  'profile.json' file in the apio home directory (e.g. '~/.apio') and
+  apply to all apio projects.
 
   Examples:
-    apio preferences set --colors on    # Enable colors.
-    apio preferences set --colors off   # Disable colors.
-
-  The apio colors are optimized for a terminal windows with a white
-  background.
+    apio preferences -t light       # Colors for light backgrounds.
+    apio preferences -t dark        # Colors for dark backgrounds.
+    apio preferences -t no-colors   # No colors.
+    apio preferences --list         # List current preferences.
+    apio pref -t dark               # Using command shortcut.
 
 Options:
-  -c, --colors [on|off]  Set/reset colors mode.  [required]
-  -h, --help             Show this message and exit.
+  -t, --theme [light|dark|no-colors]
+                                  Set colors theme name.
+  -l, --list                      List the preferences.
+  -h, --help                      Show this message and exit.
 
 ```
 

diff --git a/apio/apio_context.py b/apio/apio_context.py
@@ -14,6 +14,7 @@
 from pathlib import Path
 from typing import Optional, Dict
 from apio.common.apio_console import cout, cerror, cwarning
+from apio.common.styles import INFO
 from apio.profile import Profile
 from apio.utils import jsonc, util, env_options
 from apio.managers.project import (
@@ -101,16 +102,13 @@ def __init__(
 
         """
 
-        # -- Set color on/off based on the option profile.json.
-        Profile.apply_color_preferences()
-
         # -- Inform as soon as possible about the list of apio env options
         # -- that modify its default behavior.
         defined_env_options = env_options.get_defined()
         if defined_env_options:
             cout(
                 f"Active env options [{', '.join(defined_env_options)}].",
-                style="yellow",
+                style=INFO,
             )
 
         # -- Store the scope
@@ -235,7 +233,7 @@ def lookup_board_name(
             cerror(f"No such board '{board}'")
             cout(
                 "Run 'apio boards' for the list of board names.",
-                style="yellow",
+                style=INFO,
             )
             sys.exit(1)
 
@@ -344,7 +342,7 @@ def _load_resource_file(filepath: Path) -> dict:
 
             # -- Display Main error
             cerror("Invalid .jsonc file", f"{exc}")
-            cout(f"File: {filepath}", style="yellow")
+            cout(f"File: {filepath}", style=INFO)
 
             # -- Abort!
             sys.exit(1)
@@ -447,7 +445,7 @@ def _determine_platform_id(platforms: Dict[str, Dict]) -> str:
             cout(
                 "For the list of supported platforms "
                 "type 'apio system platforms'.",
-                style="yellow",
+                style=INFO,
             )
             sys.exit(1)
 

diff --git a/apio/commands/apio.py b/apio/commands/apio.py
@@ -121,9 +121,14 @@ def context_settings():
 """
 
 
+# We set apply_theme at the top level command to apply the color preferences
+# from profile.ini to apio_console.py before we start to parse the args. This
+# way, the correct colors applied even if the parsing fails and prints
+# a usage message.
 @click.group(
     name="apio",
     cls=ApioGroup,
+    apply_theme=True,
     subgroups=SUBGROUPS,
     help=APIO_HELP,
     short_help="Work with FPGAs with ease",

diff --git a/apio/commands/apio_boards.py b/apio/commands/apio_boards.py
@@ -15,7 +15,9 @@
 from rich.table import Table
 from rich import box
 from apio.common.apio_console import cout, cprint
+from apio.common.styles import INFO
 from apio.common import apio_console
+from apio.common.styles import BORDER, EMPH1
 from apio.apio_context import ApioContext, ApioContextScope
 from apio.utils import util, cmd_util
 from apio.commands import options
@@ -96,13 +98,13 @@ def list_boards(apio_ctx: ApioContext, verbose: bool):
         show_header=True,
         show_lines=False,
         box=box.SQUARE,
-        border_style="dim",
+        border_style=BORDER,
         title_justify="left",
         title="Apio Supported Boards",
     )
 
     # -- Add columns.
-    table.add_column("BOARD-ID", no_wrap=True, style="cyan")
+    table.add_column("BOARD-ID", no_wrap=True, style=EMPH1)
     table.add_column("EXMPLS", no_wrap=True)
     if verbose:
         table.add_column("DESCRIPTION", no_wrap=True, max_width=25)
@@ -147,7 +149,8 @@ def list_boards(apio_ctx: ApioContext, verbose: bool):
         cout(f"Total of {util.plurality(entries, 'board')}")
         if not verbose:
             cout(
-                "Run 'apio boards -v' for additional columns.", style="yellow"
+                "Run 'apio boards -v' for additional columns.",
+                style=INFO,
             )