Improve the --help menu and add the --version and -v flags to the command-line interface

.github/workflows/main.yml

@@ -68,12 +68,12 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest]
-        python-version: ["3.7", "3.10"]
+        python-version: ["3.8", "3.10"]
         include:
           - os: macos-latest
             python-version: "3.9"
           - os: windows-latest
-            python-version: "3.8"
+            python-version: "3.9"
     env:
       OS: ${{ matrix.os }}
       PYTHON: ${{ matrix.python-version }}
@@ -87,7 +87,7 @@ jobs:
       - name: Install Poetry
         uses: Gr1N/setup-poetry@v7
         with:
-          poetry-version: 1.1.13
+          poetry-version: 1.1.14
       - name: Setup Poetry
         run: |
           poetry --version

.github/workflows/publish.yml

@@ -11,10 +11,10 @@ jobs:
     steps:
       - name: Checkout repository
         uses: actions/checkout@v2
-      - name: Set up Python 3.7
+      - name: Set up Python 3.8
         uses: actions/setup-python@v2
         with:
-          python-version: '3.7'
+          python-version: '3.8'
       - name: Install Poetry
         uses: Gr1N/setup-poetry@v7
       - name: Publish

gatorgrade/main.py

@@ -1,65 +1,104 @@
-"""Use Typer to run gatorgrade to run the checks and generate the yml file."""
+"""Use Typer to run gatorgrade to run the GatorGrader checks."""
 
 import sys
 from pathlib import Path
 
 import typer
 from rich.console import Console
+from rich.markdown import Markdown
 
 from gatorgrade.input.parse_config import parse_config
 from gatorgrade.output.output import run_checks
+from gatorgrade.util import github
+from gatorgrade.util import versions
 
-# create an app for the Typer-based CLI
+# define constants used in this module
+DEFAULT_VERSION = False
+GATORGRADE_EMOJI_RICH = ":crocodile:"
+FILE = "gatorgrade.yml"
+FAILURE = 1
+RICH_MARKUP_MODE_DEFAULT = "markdown"
 
-# define the emoji that will be prepended to the help message
-gatorgrade_emoji = "🐊"
+# define the overall help message
+help_message_markdown = f"""
+{GATORGRADE_EMOJI_RICH} GatorGrade runs the GatorGrader checks in a specified configuration file.
+"""
 
-# create a Typer app that
+# create a Typer app that:
 # --> does not support completion
-# --> has a specified help message with an emoji
+# --> has a specified help message with an emoji for tagline
+# --> uses "markdown" mode so that markdown and emojis work
 app = typer.Typer(
     add_completion=False,
-    help=f"{gatorgrade_emoji} Run the GatorGrader checks in the specified gatorgrade.yml file.",
+    help=help_message_markdown,
+    rich_markup_mode=RICH_MARKUP_MODE_DEFAULT,
 )
 
 # create a default console for printing with rich
 console = Console()
 
-# define constants used in this module
-FILE = "gatorgrade.yml"
-FAILURE = 1
-
 
 @app.callback(invoke_without_command=True)
 def gatorgrade(
     ctx: typer.Context,
     filename: Path = typer.Option(FILE, "--config", "-c", help="Name of the YML file."),
+    version: bool = typer.Option(
+        DEFAULT_VERSION, "--version", "-v", help="Display version information."
+    ),
 ):
-    """Run the GatorGrader checks in the specified gatorgrade.yml file."""
+    """Run the GatorGrader checks in the specified configuration file."""
     # if ctx.subcommand is None then this means
     # that, by default, gatorgrade should run in checking mode
     if ctx.invoked_subcommand is None:
-        # parse the provided configuration file
-        checks = parse_config(filename)
-        # there are valid checks and thus the
-        # tool should run them with run_checks
-        if len(checks) > 0:
-            checks_status = run_checks(checks)
-        # no checks were created and this means
-        # that, most likely, the file was not
-        # valid and thus the tool cannot run checks
-        else:
-            checks_status = False
+        # requesting version information overrides all other commands;
+        # if the version details are requested, print them and exit
+        if version:
+            # define the version label with suitable emoji
+            version_label = ":wrench: Version information:"
+            # define the message about the project versions
+            version_message = versions.get_project_versions()
+            # define a contribution message with suitable emoji
+            contribution_message = (
+                ":tada: Want to contribute to this project? Check these GitHub sites!"
+            )
+            # define the message about GitHub repositories
+            github_message = github.get_github_projects()
+            # output all of the details about gatorgrade
+            # 1) standard help message that was defined previously
+            console.print(help_message_markdown)
+            # 2) version message
+            console.print(version_label)
+            console.print(Markdown(version_message))
             console.print()
-            console.print(f"The file {filename} either does not exist or is not valid.")
-            console.print("Exiting now!")
+            # 3) contribution message
+            console.print(contribution_message)
+            console.print(Markdown(github_message))
             console.print()
-        # at least one of the checks did not pass or
-        # the provided file was not valid and thus
-        # the tool should return a non-zero exit
-        # code to designate some type of failure
-        if checks_status is not True:
-            sys.exit(FAILURE)
+        # run the checking function since --version was not provided
+        else:
+            # parse the provided configuration file
+            checks = parse_config(filename)
+            # there are valid checks and thus the
+            # tool should run them with run_checks
+            if len(checks) > 0:
+                checks_status = run_checks(checks)
+            # no checks were created and this means
+            # that, most likely, the file was not
+            # valid and thus the tool cannot run checks
+            else:
+                checks_status = False
+                console.print()
+                console.print(
+                    f"The file {filename} either does not exist or is not valid."
+                )
+                console.print("Exiting now!")
+                console.print()
+            # at least one of the checks did not pass or
+            # the provided file was not valid and thus
+            # the tool should return a non-zero exit
+            # code to designate some type of failure
+            if checks_status is not True:
+                sys.exit(FAILURE)
 
 
 # @app.command()

gatorgrade/util/github.py

@@ -0,0 +1,36 @@
+"""Collect GitHub URLs for display in the command-line interface."""
+
+from typing import Dict
+
+COLON = ":"
+DASH = "-"
+SPACE = " "
+NEWLINE = "\n"
+NEWLINE_NEWLINE = "\n\n"
+
+PROJECTS = {
+    "gatorgrade": "https://github.com/GatorEducator/gatorgrade",
+    "gatorgrader": "https://github.com/GatorEducator/gatorgrader",
+}
+
+
+def get_github_projects(projects: Dict[str, str] = PROJECTS) -> str:
+    """Create a GitHub repository string for all specified projects."""
+    # create an empty project_version_str that will be appended
+    # to with information about each project and its GitHub URL
+    project_version_str = ""
+    # iterate through the provided projects and display:
+    # 1) the name of the project
+    # 2) the GitHub URL for the project
+    for project_name in projects.keys():
+        current_project_version_str = (
+            DASH
+            + SPACE
+            + project_name
+            + COLON
+            + SPACE
+            + projects[project_name]
+            + NEWLINE_NEWLINE
+        )
+        project_version_str = project_version_str + current_project_version_str
+    return project_version_str

gatorgrade/util/versions.py

@@ -0,0 +1,38 @@
+"""Extract version information for display in various aspects of the command-line interface."""
+
+from importlib.metadata import version
+from typing import List
+
+COLON = ":"
+DASH = "-"
+SPACE = " "
+NEWLINE = "\n"
+NEWLINE_NEWLINE = "\n\n"
+
+
+# Projects are hard-coded and may need to be updated if there are
+# new dependencies specified inside of the pyproject.toml file.
+# With that said, this approach avoids the need to parse the
+# dependencies listed in the pyproject.toml file.
+PROJECTS = ["gatorgrade", "gatorgrader", "pyyaml", "rich", "typer"]
+
+
+def get_project_version(project: str) -> str:
+    """Extract the version information for a project and return formatted version string."""
+    project_version_str = version(project)
+    return project + COLON + SPACE + project_version_str
+
+
+def get_project_versions(project_list: List[str] = PROJECTS) -> str:
+    """Create a version string for all specified projects."""
+    # create an empty version string that this function
+    # will append to for each of the projects in the project_list
+    project_version_str = ""
+    # iterate through every project in the project_list and then
+    # include its name and its current version in project_version_str
+    for project in project_list:
+        current_project_version_str = (
+            DASH + SPACE + get_project_version(project) + NEWLINE_NEWLINE
+        )
+        project_version_str = project_version_str + current_project_version_str
+    return project_version_str