Merge pull request #407 from zapta/develop

First installment of adding a detailed help text and cleaning up the flags where applicable.

apio/__main__.py

@@ -103,12 +103,28 @@ def select_commands_help(command_lines, command_names):
 # ---------------------------
 # -- Top click command node.
 # ---------------------------
+
+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 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).
+
+For more information on the apio project see
+https://github.com/FPGAwars/apio/wiki/Apio
+"""
+
+
 @click.command(
     cls=ApioCLI,
-    help=(
-        "Work with FPGAs with ease. "
-        "For more information see https://github.com/FPGAwars/apio/wiki/Apio"
-    ),
+    help=HELP,
     invoke_without_command=True,
     context_settings=util.context_settings(),
 )

apio/commands/boards.py

@@ -28,7 +28,30 @@
 # ---------------------------
 # -- COMMAND
 # ---------------------------
-@click.command("boards", context_settings=util.context_settings())
+HELP = """
+The apio boards commands provides information about the FPAG boards that are
+supported by apio. To view the list of all supported boards use the command
+
+  apio boards --list
+
+To list the supported FPGAs, replace the --list option with the
+--fpga option.
+
+Hint: apio comes with example projects for some boards. See the apio examples
+command for more information.
+
+Advanced: Boards with wide availability can be added by contacting the
+apio team. You can also add a custon one-of board definition to your apio
+project by placing a custom boards.json file in your apio project.
+"""
+
+
+@click.command(
+    "boards",
+    short_help="List supported boards and FPGAs.",
+    help=HELP,
+    context_settings=util.context_settings(),
+)
 @click.pass_context
 @options.project_dir_option
 @options.list_option_gen(help="List all supported FPGA boards.")
@@ -40,7 +63,9 @@ def cli(
     list_: bool,
     fpgas: bool,
 ):
-    """Manage FPGA boards."""
+    """Implements the 'boards' command which lists supported boards
+    and FPGAs.
+    """
 
     # -- Access to the apio resources
     resources = Resources(project_dir=project_dir)

apio/commands/clean.py

@@ -17,7 +17,23 @@
 # ---------------------------
 # -- COMMAND
 # ---------------------------
-@click.command("clean", context_settings=util.context_settings())
+HELP = """
+The apio clean command deletes the files that were generated
+in the FPGA project directory by previous apio commands.  For example:
+
+  apio clean
+
+Hint: if you are using a git repository, add a .gitignore file with
+the temporary apio file names.
+"""
+
+
+@click.command(
+    "clean",
+    short_help="Clean the apio generated files.",
+    help=HELP,
+    context_settings=util.context_settings(),
+)
 @click.pass_context
 @options.project_dir_option
 @options.board_option_gen()
@@ -29,7 +45,9 @@ def cli(
     board: str,
     verbose: bool,
 ):
-    """Clean the previous generated files."""
+    """Implements the apio clean command. It deletes temporary files generated
+    by apio commands.
+    """
 
     # -- Create the scons object
     scons = SCons(project_dir)

apio/commands/graph.py

@@ -29,7 +29,7 @@ def cli(
     verbose: bool,
     top_module: str,
 ):
-    """Generate a a visual graph of the verilog code."""
+    """Generate a visual graph of the verilog code."""
 
     # -- Crete the scons object
     scons = SCons(project_dir)

apio/commands/sim.py

@@ -13,21 +13,47 @@
 from apio import util
 from apio.commands import options
 
-
 # ---------------------------
 # -- COMMAND
 # ---------------------------
-@click.command("sim", context_settings=util.context_settings())
+
+HELP = """
+The apio sim command simulates a given testbench file and shows
+the simulation results a GTKWave graphical window. A typical invocation
+is done in the PFGA project directory where the apio.ini file and the verilog
+source files resides. The command accepts the testbench file name as
+an argument. For example:
+
+  apio sim my_module_tb.v
+
+The apio sim command defines the verilog macro INTERACTIVE_SIM. The
+presernce of this macro allows testbenches to continue and display the
+simulation signals instead of aborting the simulation.
+
+Hint: when you configure the signals in GTKWave, you can save the
+configuration for future invocations.
+"""
+
+
+@click.command(
+    "sim",
+    short_help="Simulate a testbench with graphic results.",
+    help=HELP,
+    context_settings=util.context_settings(),
+)
 @click.pass_context
+@click.argument("testbench", nargs=1)
 @options.project_dir_option
-@options.testbench
 def cli(
     ctx,
+    # Arguments
+    testbench: str,
     # Options
     project_dir: Path,
-    testbench: str,
 ):
-    """Simulate a single module."""
+    """Implements the apio sim command. It simulates a single testbench
+    file and shows graphically the signal graphs.
+    """
 
     # -- Create the scons object
     scons = SCons(project_dir)

apio/commands/time.py

@@ -45,7 +45,7 @@ def cli(
     verbose_yosys: bool,
     verbose_pnr: bool,
 ):
-    """Analyze and design and report timing."""
+    """Analyze the design and report timing."""
 
     # -- Create the scons object
     scons = SCons(project_dir)