Merge pull request #511 from zapta/develop

Cleaned up the help text of apio's commands.

apio/commands/apio.py

@@ -93,17 +93,26 @@ def context_settings():
 HELP = """
 Work with FPGAs with ease.
 
-Apio is a user friendly command-line
-suite that supports all the aspect of FPGA firmware developement
-from linting, building and simulating to unit testing, to progreamming
-the FPGA board.
+Apio is an easy to use and open-source command-line suite designed to
+streamline FPGA programming. It supports a wide range of tasks, including
+linting, building, simulation, unit testing, and programming FPGA boards.
 
-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').
+An Apio project consists of a directory containing a configuration file
+named 'apio.ini', along with FPGA source files, testbenches, and pin definition
+files.
 
-For more information on the apio project see
+Apio commands are intuitive and perform their intended functionalities right
+out of the box. For example, the command apio upload automatically compiles
+the design in the current directory and uploads it to the FPGA board.
+
+For detailed information about any Apio command, append the -h flag to view
+its help text. For instance:
+
+\b
+apio build -h
+apio drivers ftdi install -h
+
+For more information about the Apio project, visit the official Apio Wiki
 https://github.com/FPGAwars/apio/wiki/Apio
 """
 

apio/commands/apio_boards.py

@@ -99,13 +99,9 @@ def list_boards(apio_ctx: ApioContext):
 # R0801: Similar lines in 2 files
 # pylint: disable = R0801
 HELP = """
-The boards commands lists the FPGA boards that are recongnized by apio.
-Custom boards can be defined by placing a custom boards.json file in the
-project directory. If such a case, the command
-lists the boards from that custom file.
-
-The commands is typically used in the root directory
-of the project that contains the apio.ini file.
+The command 'apio boards' lists the FPGA boards recognized by Apio.
+Custom boards can be defined by placing a custom 'boards.json' file in the
+project directory, which will override Apio’s default 'boards.json' file.
 
 \b
 Examples:

apio/commands/apio_build.py

@@ -20,19 +20,17 @@
 # ---------------------------
 
 HELP = """
-The build command reads the project source files
-and generates a bitstream file that you can uploaded to your FPGA.
-The commands is typically used in the root directory
-of the project that contains the apio.ini file.
+The command 'apio build' processes the project’s source files and generates a
+bitstream file, which can then be uploaded to your FPGA.
+
+The 'apio build' command compiles all .v files (e.g., my_module.v) in the
+project directory, except those whose names end with _tb
+(e.g., my_module_tb.v), as these are assumed to be testbenches.
 
 \b
 Examples:
   apio build       # Build
   apio build -v    # Build with verbose info
-
-The build command builds all the .v files (e.g. my_module.v) in the project
-directory except for those whose name ends with _tb (e.g. my_module_tb.v) to
-indicate that they are testbenches.
 """
 
 

apio/commands/apio_clean.py

@@ -19,17 +19,13 @@
 # -- COMMAND
 # ---------------------------
 HELP = """
-The clean command deletes the temporary files that were generated
-in the project directory by previous apio commands.
-The commands is typically used in the root directory
-of the project that contains the apio.ini file.
+The command 'apio clean' removes temporary files generated in the project
+directory by previous Apio commands.
 
 \b
 Example:
   apio clean
 
-[Hint] If you are using a git repository, add a .gitignore file with
-the temporary apio file names.
 """
 
 

apio/commands/apio_create.py

@@ -11,7 +11,6 @@
 import click
 from apio.managers.project import (
     DEFAULT_TOP_MODULE,
-    APIO_INI,
     create_project_file,
 )
 from apio import util
@@ -34,23 +33,19 @@
 # ---------------------------
 # -- COMMAND
 # ---------------------------
-HELP = f"""
-The 'apio create' command creates a new apio.ini project file and may
-be use when creating a new apio project.
+HELP = """
+The command 'apio create' creates a new `apio.ini` project file and is
+typically used when setting up a new Apio project.
 
 \b
 Examples:
   apio create --board alhambra-ii
   apio create --board alhambra-ii --top-module MyModule
 
-The flag --board is required. The flag --top-module is optional and has
-the default '{DEFAULT_TOP_MODULE}'. If the file apio.ini already exists
-the command exists with an error message.
 
-[Note] this command creates just the '{APIO_INI}' file
-rather than a complete and buildable project.
-Some users use instead the'apio examples' command to copy a working
-project for their board, and then modify it with with their design.
+[Note] This command only creates a new 'apio.ini' file, rather than a complete
+and buildable project. To create complete projects, refer to the
+'apio examples' command.
 """
 
 

apio/commands/apio_drivers.py

@@ -17,16 +17,16 @@
 # --- apio drivers lsusb
 
 LSUSB_HELP = """
-The 'apio drivers lsusb' commands runs the lsusb utility to list the usb
-devices connected to your computer.  It is typically used  for diagnosing
+The command ‘apio drivers lsusb’ runs the lsusb utility to list the USB
+devices connected to your computer. It is typically used for diagnosing
 connectivity issues with FPGA boards.
 
 \b
 Examples:
   apio drivers lsusb      # List the usb devices
 
 [Hint] You can also run the lsusb utility using the command
-'apio raw -- lsusb <flags>'
+'apio raw -- lsusb <flags>'.
 """
 
 
@@ -52,10 +52,8 @@ def _lsusb_cli():
 # --- apio drivers
 
 DRIVERS_HELP = """
-The 'apio drivers' commands group contains subcommands that are used
-to manage the drivers on your system.
-
-The subcommands are listed below.
+The command group ‘apio drivers’ contains subcommands used to manage the
+drivers on your system.
 """
 
 # -- We have only a single group with the title 'Subcommands'.

apio/commands/apio_drivers_ftdi.py

@@ -18,8 +18,8 @@
 # -- apio drivers ftdi install
 
 INSTALL_HELP = """
-The command 'apio drivers ftdi install' installs the ftdi drivers on your
-system as required by some FPGA boards.
+The command 'apio drivers ftdi install' installs on your system the FTDI
+drivers required by some FPGA boards.
 
 \b
 Examples:
@@ -51,8 +51,8 @@ def _install_cli():
 # -- apio driver ftdi uninstall
 
 UNINSTALL_HELP = """
-The command 'apio drivers ftdi uninstall' uninstalled the ftdi drivers that
-you may installed eariler. .
+The command 'apio drivers ftdi uninstall' removes the FTDI drivers that may
+have been installed earlier.
 
 \b
 Examples:
@@ -85,15 +85,16 @@ def _uninstall_cli():
 
 
 LIST_HELP = """
-The command 'apio drivers ftdi list' lists the ftdi devices connected
-to your computer. It is useful for diagnosing FPGA board connectivity issues.
+The command 'apio drivers ftdi list' displays the FTDI devices currently
+connected to your computer. It is useful for diagnosing FPGA board
+connectivity issues.
 
 \b
 Examples:
   apio drivers ftdi list     # List the ftdi devices.
 
-[Hint] This command executes the utility `lsftdi` which can also be invoked
-using the command `apio raw -- lsftdi <flags>`
+[Hint] This command uses the lsftdi utility, which can also be invoked
+directly with the 'apio raw -- lsftdi <flags>' command.
 """
 
 
@@ -119,10 +120,8 @@ def _list_cli():
 # --- apio drivers ftdi
 
 FTDI_HELP = """
-The 'apio drivers ftdi' commands group contains subcommands that are used
-to manage the ftdi drivers on your system.
-
-The subcommands are listed below.
+The command group 'apio drivers ftdi' includes subcommands that help manage
+the FTDI drivers on your system.
 """
 
 # -- We have only a single group with the title 'Subcommands'.

apio/commands/apio_drivers_serial.py

@@ -18,8 +18,8 @@
 # -- apio driver serial install
 
 INSTALL_HELP = """
-The command 'apio drivers serial install' installs the serial drivers on your
-system as required by some FPGA boards.
+The command ‘apio drivers serial install’ installs the necessary serial
+drivers on your system, as required by certain FPGA boards.
 
 \b
 Examples:
@@ -50,8 +50,8 @@ def _install_cli():
 # -- apio drivers serial uninstall
 
 UNINSTALL_HELP = """
-The command 'apio drivers serial uninstall' uninstalled the serial drivers that
-you may installed eariler. .
+The command ‘apio drivers serial uninstall’ removes the serial drivers that
+you may have installed earlier.
 
 \b
 Examples:
@@ -83,15 +83,15 @@ def _uninstall_cli():
 # -- apio drivers serial list
 
 LIST_HELP = """
-The command 'apio drivers serial list' lists the serial devices connected
-to your computer. It is useful for diagnosing FPGA board connectivity issues.
+The command ‘apio drivers serial list’ lists the serial devices connected to
+your computer. It is useful for diagnosing FPGA board connectivity issues.
 
 \b
 Examples:
   apio drivers serial list     # List the serial devices.
 
-[Hint] This command executes the utility `lsserial` which can also be invoked
-using the command `apio raw -- lsserial <flags>`
+[Hint] This command executes the utility lsserial, which can also be invoked
+using the command 'apio raw -- lsserial <flags>'.
 """
 
 
@@ -117,10 +117,8 @@ def _list_cli():
 # --- apio drivers serial
 
 SERIAL_HELP = """
-The 'apio drivers serial' commands group contains subcommands that are used
-to manage the serial drivers on your system.
-
-The subcommands are listed below.
+The command group 'apio drivers serial' includes subcommands designed to
+manage and configure the serial drivers on your system.
 """
 
 # -- We have only a single group with the title 'Subcommands'.

apio/commands/apio_examples.py

@@ -21,8 +21,8 @@
 
 
 LIST_HELP = """
-The 'apio examples list' lists the apio project examples that are available
-for fetching.
+The command ‘apio examples list’ lists the available Apio project examples
+that you can use.
 
 \b
 Examples:
@@ -56,17 +56,17 @@ def _list_cli():
 
 
 FETCH_HELP = """
-The 'apio examples fetch' command fetchs the files of the specified
-example to the current directory rot to the directory specified by the
---dst option. The destination directory does not have to exist but if it does
-it must be empty.
+The command ‘apio examples fetch’ fetches the files of the specified example
+to the current directory or to the directory specified by the –dst option.
+The destination directory does not need to exist, but if it does, it must be
+empty.
 
 \b
 Examples:
   apio examples fetch alhambra-ii/ledon
   apio examples fetch alhambra-ii/ledon -d foo/bar
 
-For a list of available examples type 'apio examples list'.
+[Hint] For the list of available examples, type ‘apio examples list’.
 """
 
 
@@ -101,15 +101,16 @@ def _fetch_cli(
 
 
 FETCH_BOARD_HELP = """
-The 'apio examples fetch-board` is used to fetch all the apio examples
-of a given board. The examples are copied under the current directory or
-the destination directory if --dst is given.
+The command ‘apio examples fetch-board’ is used to fetch all the Apio examples
+for a specific board. The examples are copied to the current directory or to
+the specified destination directory if the –dst option is provided.
 
 \b
 Examples:
   apio examples fetch-board alhambra-ii             # Fetch to local directory
   apio examples fetch-board alhambra-ii -d foo/bar  # Fetch to foo/bar
 
+[Hint] For the list of available examples, type ‘apio examples list’.
 """
 
 
@@ -146,12 +147,9 @@ def _fetch_board_cli(
 # ---- apio examples
 
 EXAMPLES_HELP = """
-The 'apio examples' group provides subcommands for listing and fetching
-apio provided examples, each is a self contain mini project that can be
-built and uploaded to a FPGA.
-
-The subcommands are listed below.
-
+The command group ‘apio examples’ provides subcommands for listing and
+fetching Apio-provided examples. Each example is a self-contained mini-project
+that can be built and uploaded to an FPGA board.
 """
 
 

apio/commands/apio_format.py

@@ -22,37 +22,35 @@
 # -- COMMAND
 # ---------------------------
 HELP = """
-The format command formats verilog source files for consistency and style
-but without changing their semantic.  The command accepts the names of the
-source files to format or formats all the project source files by default.
-The commands is typically used in the root directory
-of the project that contains the apio.ini file.
+The command ‘apio format’ formats Verilog source files to ensure consistency
+and style without altering their semantics. The command accepts the names of
+pecific source files to format or formats all project source files by default.
 
 \b
 Examples:
   apio format                    # Format all source files.
   apio format -v                 # Same as above but with verbose output.
   apio format main.v main_tb.v   # Format the two tiven files.
 
-The format command uses the format tool of the Verible project which can be
-configured by setting its flags in the apio.ini project file.
+The format command utilizes the format tool from the Verible project, which
+can be configured by setting its flags in the apio.ini project file
 For example:
 
 \b
 format-verible-options =
     --column_limit=80
     --indentation_spaces=4
 
-If you want to protect a group of source code lines from formatting, you
-can use the following verible formatter's directives:
+If needed, sections of source code can be protected from formatting using
+Verible formatter directives:
 
 \b
 // verilog_format: off
 ... untouched code ...
 // verilog_format: on
 
-For the ull list of the verible formatter flags, see its documentation page
-online or type 'apio raw -- verible-verilog-format --helpfull'.
+For a full list of Verible formatter flags, refer to the documentation page
+online or use the command 'apio raw -- verible-verilog-format --helpful'.
 """