CLI Documentation update / CLI small bug fixes and format updates (#726)

* updated describe commands to output entries in title format to be consistent

* fixed error where calling 'geoips' without any arguments would cause an index error

* fixed small bug where columns didn't work with geoips list packages

* updated CLI documentation to reflect current state of the CLI

* updated geoips list packages unit test for new changes

* added release notes for this PR

docs/source/releases/latest/CLI-documentation-update-for-workshop.yaml

@@ -0,0 +1,29 @@
+bug fix:
+- description: |
+    This PR fixed small bugs and formatting inconsistencies with the CLI. Specifically,
+    this PR addressed the format of the output of 'geoips describe' commands, to make
+    the keys in the yaml output all be in title format rather than (some_val:) vs.
+    (Some Val:). In this PR we were working on getting CLI documentation up to date,
+    and discovered a bug with 'geoips list packages' where the '--columns' flag was not
+    actually working. This was a simple fix and that functionality is now working as
+    expected. Unit tests have been updated to address these changes.
+  files:
+    modified:
+      - geoips/commandline/commandline_interface.py
+      - geoips/commandline/geoips_command.py
+      - geoips/commandline/geoips_describe.py
+      - geoips/commandline/geoips_list.py
+      - tests/unit_tests/commandline/test_geoips_describe_interface.py
+      - tests/unit_tests/commandline/test_geoips_plugin.py
+      - tests/unit_tests/commandline/test_geoips_list_packages.py
+  title: 'CLI Bug Fixes and Formatting Updates'
+documentation:
+- description: |
+    This PR updated the CLI documentation to reflect the current state of the CLI code.
+    Largely, this PR went through the documentation of the CLI commands and made sure
+    that what was documented matched what would actually happen when that command was
+    ran. There was a duplicate entry in the documentation that was removed as well.
+  files:
+    modified:
+      - docs/source/userguide/commandl_line.rst
+  title: 'Updated CLI Documentation to reflect the current state of the CLI'

docs/source/userguide/command_line.rst

@@ -47,8 +47,8 @@ Information Retrieval
 
 The GeoIPS CLI Implements two top-level commands which retrieve information about GeoIPS
 artifacts based on the sub-commands provided. These two top-level commands are
-``describe`` and ``list`` (``ls``). Each command shown below can be ran with a ``-h``
-flag to provide help instructions for the command you are running.
+``describe`` (``desc``) and ``list`` (``ls``). Each command shown below can be ran with
+a ``-h`` flag to provide help instructions for the command you are running.
 
 .. _geoips_describe:
 
@@ -58,7 +58,7 @@ Describe Command
 :ref:`geoips describe <geoips_describe>`
 
 ``describe`` is a GeoIPS CLI command which retrieves information specific to a single
-GeoIPS artifact. The purpose of any ``describe`` command is to describe the selected
+GeoIPS artifact. The purpose of any ``describe`` command is to lay out the selected
 GeoIPS artifact in a verbose manner. While the outputted information may differ by each
 describe  command, the ultimate purpose of each command is to provide both users and
 developers detailed information about each artifact. This will help implementing their
@@ -101,48 +101,53 @@ included when calling this command is:
 
     * Docstring
     * Family Name
+    * Family Path
     * Interface Name
     * Interface Type
     * Required Args / Schema
 
-For an example of how to run this command, see below. If you want more information about
+For an example of how to run this command, see below. Notice the use of aliases in case
+you want to use these commands in shorthand style. If you want more information about
 what families belong to a certain interface, run the command ``geoips list interfaces``,
-which will include a column representing the supported families of each interface.
+which will include a column representing the supported families of each interface. You
+can also run ``geoips list interfaces --columns interface supported_families`` for a
+concise depiction of what families belong to each interface.
 
 ::
 
+    geoips describe alg fam single_channel
+    geoips describe algs fam single_channel
+    geoips describe algorithm family single_channel
     geoips describe algorithms family single_channel
+    geoips describe prod-def fam interpolator_algorithm_colormapper
+    geoips describe prod-defs fam interpolator_algorithm_colormapper
+    geoips describe product_default family interpolator_algorithm_colormapper
+    geoips describe product_defaults family interpolator_algorithm_colormapper
     geoips describe <interface_name> family <family_name>
 
 .. _geoips_describe_package:
 
 :ref:`geoips describe package <geoips_describe_package>`
 
-``describe package`` is a describe sub-command which retrieves information specific to a
-GeoIPS Package. Information included when calling this command is:
+``describe package <package_name>`` (or ``describe pkg <package_name>``) is a describe
+sub-command which retrieves information specific to a GeoIPS Package. Information
+included when calling this command is:
 
     * Docstring
-    * Family Name
-    * Interface Name
-    * Interface Type
-    * Required Args / Schema
+    * GeoIPS Package
+    * Package Path
+    * Source Code
+    * Version Number
 
 For an example of how to run this command, see below. Notice the use of aliases in case
 you want to use these commands in shorthand style. If you want more information about
-what families belong to a certain interface, run the command ``geoips list interfaces``,
-which will include a column representing the supported families of each interface.
+what GeoIPS Packages are available, run the command ``geoips list packages``.
 
 ::
 
-    geoips describe alg fam single_channel
-    geoips describe algs fam single_channel
-    geoips describe algorithm family single_channel
-    geoips describe algorithms family single_channel
-    geoips describe prod-def fam interpolator_algorithm_colormapper
-    geoips describe prod-defs fam interpolator_algorithm_colormapper
-    geoips describe product_default family interpolator_algorithm_colormapper
-    geoips describe product_defaults family interpolator_algorithm_colormapper
-    geoips describe <interface_name> family <family_name>
+    geoips describe pkg geoips
+    geoips describe package geoips
+    geoips describe package <package_name>
 
 .. _geoips_describe_plugin:
 
@@ -157,11 +162,18 @@ is:
     * Interface
     * GeoIPS Package
     * Plugin Type
+    * Product Defaults (if applicable)
     * Relative Path
+    * Signature (if applicable)
+    * Source Names (if applicable)
+
 
 For an example of how to run this command, see below. Notice the use of aliases in case
 you want to use these commands in shorthand style. If you want more information about
-what plugins are available, run the command ``geoips list plugins``.
+what plugins are available, run the command ``geoips list plugins``. Note, if you are
+trying to describe a product, the plugin name is a combination of it's source name and
+product name. I.e. for the product ``Infrared`` coming from source ``abi``, the command
+call would look like ``geoips describe product abi.Infrared``.
 
 ::
 
@@ -171,26 +183,6 @@ what plugins are available, run the command ``geoips list plugins``.
     geoips describe algorithms single_channel
     geoips describe <interface_name> <plugin_name>
 
-``describe package <package_name>`` (or ``describe pkg <package_name>``) is a describe
-sub-command which retrieves information specific to a GeoIPS Package. Information
-included when calling this command is:
-
-    * Docstring
-    * GeoIPS Package
-    * Package Path
-    * Source Code
-    * Version Number
-
-For an example of how to run this command, see below. Notice the use of aliases in case
-you want to use these commands in shorthand style. If you want more information about
-what GeoIPS Packages are available, run the command ``geoips list packages``.
-
-::
-
-    geoips desc pkg geoips
-    geoips describe package geoips
-    geoips describe package <package_name>
-
 .. _geoips_list:
 
 List Command
@@ -230,10 +222,10 @@ can filter by, run ``geoips list <cmd_name> --columns help``.
 plugins of a certain interface. This can also be applied to a certain GeoIPS package.
 Information included when calling this command is:
 
-    * Family
-    * GeoIPS Packages
+    * GeoIPS Package
     * Interface Name
     * Interface Type
+    * Family
     * Plugin Name
     * Source Names (if applicable)
     * Relative Path
@@ -321,6 +313,7 @@ this command is:
     * Interface Type
     * Family
     * Plugin Name
+    * Source Names
     * Relative Path
 
 For an example of how to run this command, see below. Notice the use of aliases in case
@@ -341,7 +334,7 @@ plugins from a certain GeoIPS package.
 all, or a certain GeoIPS Package. For this command to find your test script, you must
 place the script under ``<package_name>/tests/scripts/``. These test scripts can then be
 ran using ``geoips run <package_name> <script_name>``. This command can only be ran if
-the specified plugin package[s] are installed in *editable* mode.
+the specified plugin package(s) are installed in *editable* mode.
 Information included when calling this command is:
 
     * GeoIPS Package
@@ -396,7 +389,7 @@ you want to use these commands in shorthand style.
 all, or a certain GeoIPS Package. For this command to find your unit tets, you must
 place the unit tests under ``<package_name>/tests/unit_tests/``. These test scripts can
 then be ran using ``pytest -v /path/to/<package_name/tests/unit_tests/<unit_test_dir>``.
-This command can only be ran if the specified plugin package[s] are installed in
+This command can only be ran if the specified plugin package(s) are installed in
 *editable* mode.
 Information included when calling this command is:
 
@@ -600,7 +593,7 @@ To produce a sector image is quite simple. All you have to do is:
 
     * ``geoips test sector <sector_name>``
 
-This an additional output directory can be specified if you want this image to be saved
+An additional output directory can be specified if you want the sector image to be saved
 in a different location.
 
     * ``geoips test sector <sector_name> --outdir <output_directory_path>``
@@ -664,12 +657,44 @@ The output of running ``geoips tree`` is shown below.
         geoips config
             geoips config install
         geoips describe
-            geoips describe family
-            geoips describe interface
+            geoips describe algorithms
+            geoips describe colormappers
+            geoips describe coverage-checkers
+            geoips describe feature-annotators
+            geoips describe filename-formatters
+            geoips describe gridline-annotators
+            geoips describe interpolators
+            geoips describe output-checkers
+            geoips describe output-formatters
+            geoips describe procflows
+            geoips describe product-defaults
+            geoips describe products
+            geoips describe readers
+            geoips describe sector-adjusters
+            geoips describe sector-metadata-generators
+            geoips describe sector-spec-generators
+            geoips describe sectors
+            geoips describe title-formatters
             geoips describe package
-            geoips describe plugin
         geoips list
-            geoips list interface
+            geoips list algorithms
+            geoips list colormappers
+            geoips list coverage-checkers
+            geoips list feature-annotators
+            geoips list filename-formatters
+            geoips list gridline-annotators
+            geoips list interpolators
+            geoips list output-checkers
+            geoips list output-formatters
+            geoips list procflows
+            geoips list product-defaults
+            geoips list products
+            geoips list readers
+            geoips list sector-adjusters
+            geoips list sector-metadata-generators
+            geoips list sector-spec-generators
+            geoips list sectors
+            geoips list title-formatters
             geoips list interfaces
             geoips list packages
             geoips list plugins
@@ -683,18 +708,19 @@ The output of running ``geoips tree`` is shown below.
         geoips test
             geoips test linting
             geoips test script
+            geoips test sector
         geoips tree
         geoips validate
 
 ``geoips tree`` additionaly provides optional arguments to filter the output of this
 command. Shown below are these optional arguments and descriptions of what each argument
 does.
 
-* ``--colored``
+* ``--color``
 
   * The output of ``geoips tree`` might be a little hard to interpret. If you want the
-    output of ``geoips tree`` to be colored by depth, make sure to use the ``--colored``
-    flag. (Defaults to False)
+    output of ``geoips tree`` to be highlighted by depth, make sure to use the
+    ``--color`` flag. (Defaults to False)
 
 * ``--max-depth``
 
@@ -728,7 +754,7 @@ certain plugin. To get a listing of plugins available for validation, run the co
 the package we want to list plugins from.
 
 To validate a plugin we will need the full path to the plugin you want validated. See
-an example of this shown below.Notice the use of aliases in case
+an example of this shown below. Notice the use of aliases in case
 you want to use these commands in shorthand style.
 
 ::

geoips/commandline/commandline_interface.py

@@ -115,6 +115,7 @@ def support_legacy_procflows():
     supported_procflows = ["config_based", "data_fusion", "single_source"]
     if (
         basename(sys.argv[0]) == "geoips"
+        and len(sys.argv) > 2
         and sys.argv[1] == "run"
         and (len(sys.argv) < 3 or sys.argv[2] not in supported_procflows)
     ):

geoips/commandline/geoips_command.py

@@ -339,6 +339,11 @@ def _output_dictionary_highlighted(self, dict_entry):
             # Color the keys in cyan and values in yellow
             if ":" in line:
                 key, value = line.split(":", 1)
+                key = key.title().replace("_", " ")
+                if key in ["Package", "Geoips Package"]:
+                    key = "GeoIPS Package"
+                elif key == "Relpath":
+                    key = "Relative Path"
                 formatted_line = Fore.CYAN + key + ":" + Style.RESET_ALL
                 formatted_line += Fore.YELLOW + value + Style.RESET_ALL
                 print(formatted_line)

geoips/commandline/geoips_describe.py

@@ -268,11 +268,11 @@ def describe_interface(self):
             / f"interfaces/{interface.interface_type}/{interface.name}.py"
         )
         interface_entry = {
-            "interface": interface.name,
-            "interface_type": interface.interface_type,
-            "docstring": format_docstring(interface.__doc__),
-            "abspath": interface_path,
-            "supported_families": interface.supported_families,
+            "Interface": interface.name,
+            "Interface Type": interface.interface_type,
+            "Docstring": format_docstring(interface.__doc__),
+            "Absolute Path": interface_path,
+            "Supported Families": interface.supported_families,
         }
         self._output_dictionary_highlighted(interface_entry)
 

geoips/commandline/geoips_list.py

@@ -416,7 +416,7 @@ def __call__(self, args):
 
             pkg_entry = []
             docstring = import_module(package_name).__doc__
-            for header in default_headers:
+            for header in headers:
                 if header == "package":
                     pkg_name_requested = True
                     pkg_entry.append(package_name)

tests/unit_tests/commandline/test_geoips_describe_interface.py

@@ -69,11 +69,11 @@ def check_output(self, args, output):
         else:
             # Checking that output from geoips describe package command is valid
             expected_outputs = [
-                "abspath",
-                "docstring",
-                "interface",
-                "interface_type",
-                "supported_families",
+                "Absolute Path",
+                "Docstring",
+                "Interface",
+                "Interface Type",
+                "Supported Families",
             ]
             for output_item in expected_outputs:
                 assert f"{output_item}:" in output

tests/unit_tests/commandline/test_geoips_describe_plugin.py

@@ -107,12 +107,12 @@ def check_output(self, args, output):
             # Checking that output from geoips describe plugin command is valid
             interface_name = args[3]
             expected_outputs = [
-                "docstring",
-                "family",
-                "interface",
-                "package",
-                "plugin_type",
-                "relpath",
+                "Docstring",
+                "Family",
+                "Interface",
+                "Package",
+                "Plugin Type",
+                "Relative Path",
             ]
             if interface_name == "products":
                 expected_outputs.append("source_names")

tests/unit_tests/commandline/test_geoips_list_packages.py

@@ -100,7 +100,8 @@ def check_output(self, args, output):
             self.assert_correct_headers_in_output(output, headers, selected_cols)
             # Assert that we found every installed package
             for pkg_name in self.plugin_package_names:
-                assert pkg_name in output
+                if "--columns" not in args or "package" in selected_cols:
+                    assert pkg_name in output
 
 
 test_sub_cmd = TestGeoipsListPackages()