Added printing of an info message when a deprecated command flag is u…

…sed, while preseving the functionality of the deprecated flags. This change was implemented using custom click handler classes called ApioOption and ApioCommand that handles the deprecation programatically.

apio/__main__.py

@@ -103,6 +103,16 @@ def select_commands_help(command_lines, command_names):
     return result
 
 
+def context_settings():
+    """Return a common Click command settings that adds
+    the alias -h to --help. This applies also to all the sub
+    commands such as apio build.
+    """
+    # Per https://click.palletsprojects.com/en/8.1.x/documentation/
+    #     #help-parameter-customization
+    return {"help_option_names": ["-h", "--help"]}
+
+
 # ---------------------------
 # -- Top click command node.
 # ---------------------------
@@ -118,7 +128,7 @@ def select_commands_help(command_lines, command_names):
 Apio commands are typically invoked in the root directory of the FPGA
 project where the project configuration file apio.ini and the project
 source files are stored. For help on specific commands use the -h
-flag (e.g. apio build -h).
+flag (e.g. 'apio build -h').
 
 For more information on the apio project see
 https://github.com/FPGAwars/apio/wiki/Apio
@@ -129,7 +139,7 @@ def select_commands_help(command_lines, command_names):
     cls=ApioCLI,
     help=HELP,
     invoke_without_command=True,
-    context_settings=util.context_settings(),
+    context_settings=context_settings(),
 )
 @click.pass_context
 @click.version_option()

apio/commands/boards.py

@@ -5,7 +5,7 @@
 # --  * Jesús Arroyo (2016-2019)
 # --  * Juan Gonzalez (obijuan) (2019-2024)
 # -- Licence GPLv2
-"""Main implementation of APIO BOARDS command"""
+"""Implementation of 'apio boards' command"""
 
 from pathlib import Path
 import click
@@ -23,6 +23,7 @@
     "--fpga",
     is_flag=True,
     help="List supported FPGA chips.",
+    cls=util.ApioOption,
 )
 
 
@@ -50,7 +51,7 @@
     "boards",
     short_help="List supported boards and FPGAs.",
     help=HELP,
-    context_settings=util.context_settings(),
+    cls=util.ApioCommand,
 )
 @click.pass_context
 @options.project_dir_option

apio/commands/build.py

@@ -5,7 +5,7 @@
 # --  * Jesús Arroyo (2016-2019)
 # --  * Juan Gonzalez (obijuan) (2019-2024)
 # -- Licence GPLv2
-"""Main implementation of APIO BUILD command"""
+"""Implementation of 'apio build' command"""
 
 from pathlib import Path
 import click
@@ -29,10 +29,6 @@
 Examples:
   apio build
   apio build -v
-
-[Note] The flags marked with (deprecated) are not recomanded.
-Instead, use an apio.ini project config file and if neaded, add
-to the project custom boards.json and fpga.json files.
 """
 
 
@@ -42,15 +38,15 @@
     "build",
     short_help="Synthesize the bitstream.",
     help=HELP,
-    context_settings=util.context_settings(),
+    cls=util.ApioCommand,
 )
 @click.pass_context
 @options.project_dir_option
 @options.verbose_option
 @options.verbose_yosys_option
 @options.verbose_pnr_option
-@options.top_module_option_gen()
-@options.board_option_gen()
+@options.top_module_option_gen(deprecated=True)
+@options.board_option_gen(deprecated=True)
 @options.fpga_option
 @options.size_option
 @options.type_option

apio/commands/clean.py

@@ -5,7 +5,7 @@
 # --  * Jesús Arroyo (2016-2019)
 # --  * Juan Gonzalez (obijuan) (2019-2024)
 # -- Licence GPLv2
-"""Main implementation of APIO CLEAN command"""
+"""Implementation of 'apio clean' command"""
 
 from pathlib import Path
 import click
@@ -28,10 +28,6 @@
 Example:
   apio clean
 
-[Note] The flags marked with (deprecated) are not recomanded.
-Instead, use an apio.ini project config file and if neaded, add
-to the project custom boards.json and fpga.json files.
-
 [Hint] If you are using a git repository, add a .gitignore file with
 the temporary apio file names.
 """
@@ -41,12 +37,12 @@
     "clean",
     short_help="Clean the apio generated files.",
     help=HELP,
-    context_settings=util.context_settings(),
+    cls=util.ApioCommand,
 )
 @click.pass_context
 @options.project_dir_option
 @options.verbose_option
-@options.board_option_gen()
+@options.board_option_gen(deprecated=True)
 def cli(
     ctx: Context,
     # Options

apio/commands/create.py

@@ -5,7 +5,7 @@
 # --  * Jesús Arroyo (2016-2019)
 # --  * Juan Gonzalez (obijuan) (2019-2024)
 # -- Licence GPLv2
-"""Main implementation of APIO CREATE command"""
+"""Implementation of 'apio create' command"""
 
 from pathlib import Path
 import click
@@ -50,7 +50,7 @@
     "create",
     short_help="Create an apio.ini project file.",
     help=HELP,
-    context_settings=util.context_settings(),
+    cls=util.ApioCommand,
 )
 @click.pass_context
 @options.board_option_gen(help="Set the board.", required=True)

apio/commands/drivers.py

@@ -5,7 +5,7 @@
 # --  * Jesús Arroyo (2016-2019)
 # --  * Juan Gonzalez (obijuan) (2019-2024)
 # -- Licence GPLv2
-"""Main implementation of APIO DRIVERS command"""
+"""Implementation of 'apio drivers' command"""
 
 import click
 from click.core import Context
@@ -20,27 +20,31 @@
     "--ftdi-enable",
     is_flag=True,
     help="Enable FTDI drivers.",
+    cls=util.ApioOption,
 )
 
 ftdi_disable_option = click.option(
     "ftdi_disable",  # Var name.
     "--ftdi-disable",
     is_flag=True,
     help="Disable FTDI drivers.",
+    cls=util.ApioOption,
 )
 
 serial_enable_option = click.option(
     "serial_enable",  # Var name.
     "--serial-enable",
     is_flag=True,
     help="Enable Serial drivers.",
+    cls=util.ApioOption,
 )
 
 serial_disable_option = click.option(
     "serial_disable",  # Var name.
     "--serial-disable",
     is_flag=True,
     help="Disable Serial drivers.",
+    cls=util.ApioOption,
 )
 
 
@@ -68,7 +72,7 @@
     "drivers",
     short_help="Manage the operating system drivers.",
     help=HELP,
-    context_settings=util.context_settings(),
+    cls=util.ApioCommand,
 )
 @click.pass_context
 @frdi_enable_option

apio/commands/examples.py

@@ -5,7 +5,7 @@
 # --  * Jesús Arroyo (2016-2019)
 # --  * Juan Gonzalez (obijuan) (2019-2024)
 # -- Licence GPLv2
-"""Main implementation of APIO EXAMPLES command"""
+"""Implementation of 'apio examples' command"""
 
 from pathlib import Path
 import click
@@ -24,6 +24,7 @@
     type=str,
     metavar="name",
     help="Copy the selected example directory.",
+    cls=util.ApioOption,
 )
 
 files_option = click.option(
@@ -33,6 +34,7 @@
     type=str,
     metavar="name",
     help="Copy the selected example files.",
+    cls=util.ApioOption,
 )
 
 
@@ -58,7 +60,7 @@
     "examples",
     short_help="List and fetch apio examples.",
     help=HELP,
-    context_settings=util.context_settings(),
+    cls=util.ApioCommand,
 )
 @click.pass_context
 @options.list_option_gen(help="List all available examples.")

apio/commands/graph.py

@@ -5,7 +5,7 @@
 # --  * Jesús Arroyo (2016-2019)
 # --  * Juan Gonzalez (obijuan) (2019-2024)
 # -- Licence GPLv2
-"""Main implementation of APIO GRAPH command"""
+"""Implementation of 'apio graph' command"""
 
 from pathlib import Path
 import click
@@ -42,7 +42,7 @@
     "graph",
     short_help="Generate a visual graph of the code.",
     help=HELP,
-    context_settings=util.context_settings(),
+    cls=util.ApioCommand,
 )
 @click.pass_context
 @options.project_dir_option

apio/commands/init.py

@@ -5,7 +5,7 @@
 # --  * Jesús Arroyo (2016-2019)
 # --  * Juan Gonzalez (obijuan) (2019-2024)
 # -- Licence GPLv2
-"""Main implementation of APIO INIT command"""
+"""Implementation of 'apio init' command"""
 
 # pylint: disable=fixme
 # TODO: After migrating IceStudio to the create/modify commands, delete
@@ -28,6 +28,7 @@
     "--scons",
     is_flag=True,
     help="(Advanced, for developers) Create default SConstruct file.",
+    cls=util.ApioOption,
 )
 
 
@@ -44,9 +45,9 @@
 # pylint: disable=R0913
 @click.command(
     "init",
-    short_help="(deprecated) Manage apio projects.",
+    short_help="[DEPRECATED] Manage apio projects.",
     help=HELP,
-    context_settings=util.context_settings(),
+    cls=util.ApioCommand,
 )
 @click.pass_context
 @options.board_option_gen(help="Create init file with the selected board.")

apio/commands/install.py

@@ -5,7 +5,7 @@
 # --  * Jesús Arroyo (2016-2019)
 # --  * Juan Gonzalez (obijuan) (2019-2024)
 # -- Licence GPLv2
-"""Main implementation of APIO INSTALL command"""
+"""Implementation of 'apio install' command"""
 
 from pathlib import Path
 from typing import Tuple
@@ -60,7 +60,7 @@ def install_packages(
     "install",
     short_help="Install apio packages.",
     help=HELP,
-    context_settings=util.context_settings(),
+    cls=util.ApioCommand,
 )
 @click.pass_context
 @click.argument("packages", nargs=-1, required=False)

apio/commands/lint.py

@@ -5,7 +5,7 @@
 # --  * Jesús Arroyo (2016-2019)
 # --  * Juan Gonzalez (obijuan) (2019-2024)
 # -- Licence GPLv2
-"""Main implementation of APIO LINT command"""
+"""Implementation of 'apio lint' command"""
 
 from pathlib import Path
 import click
@@ -23,6 +23,7 @@
     "--nostyle",
     is_flag=True,
     help="Disable all style warnings.",
+    cls=util.ApioOption,
 )
 
 
@@ -32,6 +33,7 @@
     type=str,
     metavar="nowarn",
     help="Disable specific warning(s).",
+    cls=util.ApioOption,
 )
 
 warn_option = click.option(
@@ -40,6 +42,7 @@
     type=str,
     metavar="warn",
     help="Enable specific warning(s).",
+    cls=util.ApioOption,
 )
 
 
@@ -57,8 +60,6 @@
 \b
 Examples:
   apio lint
-
-[Note] The flags marked with (deprecated) are not recomanded for use.
 """
 
 
@@ -68,7 +69,7 @@
     "lint",
     short_help="Lint the verilog code.",
     help=HELP,
-    context_settings=util.context_settings(),
+    cls=util.ApioCommand,
 )
 @click.pass_context
 @options.all_option_gen(
@@ -78,7 +79,7 @@
 @nowarn_option
 @warn_option
 @options.project_dir_option
-@options.top_module_option_gen()
+@options.top_module_option_gen(deprecated=True)
 def cli(
     ctx: Context,
     # Options

apio/commands/modify.py

@@ -5,7 +5,7 @@
 # --  * Jesús Arroyo (2016-2019)
 # --  * Juan Gonzalez (obijuan) (2019-2024)
 # -- Licence GPLv2
-"""Main implementation of APIO MODIFY command"""
+"""Implementation of 'apio modify' command"""
 
 from pathlib import Path
 import click
@@ -42,7 +42,7 @@
     "modify",
     short_help="Modify the apio.ini project file.",
     help=HELP,
-    context_settings=util.context_settings(),
+    cls=util.ApioCommand,
 )
 @click.pass_context
 @options.board_option_gen(help="Set the board.")