WIP, ENH: rich-click CLI

* related to gh-808

* adopt [`rich-click`](https://github.com/ewels/rich-click) for the
pydarshan summary report CLI, with basic usage and heatmap option
blocks

* switch to `darshan_summary` as a console script that doesn't
require prefixing with `python -m ..`; so new incantation looks
like `darshan_summary --log_path treddy_runtime_heatmap_inactive_ranks.darshan`
and reports the processing time in seconds automatically

* there were two motivations for the above change:
1) simplify the command the user needs to remember
2) I almost always want to know how long the processing took,
so report that time by default

* this is just a skeleton, and doesn't actually hook in the
HEATMAP options to actual changes in the report (yet); one other
caveat is that the console script is less friendly for developers
that use an "editable install" so you need to use `pip install .`
instead of `pip install -e .`, which is a bit annoying, but probably
lower priority than user experience concerns/improvements

* some TODOs may include:

- [ ] remove the old `argparse` CLI interface and hook the new
`click`-based CLI interface into the testsuite somehow
- [ ] actually implement the heatmap option effects (though
this can probably be handled separately, other PRs dealing with
that stuff already..)
- [ ] discuss the initial set of options we want and how we want
to group them into sections
- [ ] decide if the extra dependencies are worth it for the
CLI improvements (probably?)

Author: tylerjereddy

darshan-util/pydarshan/darshan/cli/darshan_summary.py

@@ -0,0 +1,76 @@
+import os
+import sys
+import time
+
+if sys.version_info >= (3, 7):
+    import importlib.resources as importlib_resources
+else:
+    import importlib_resources
+
+import darshan
+from darshan.cli.summary import ReportData
+
+import rich_click as click
+from mako.template import Template
+
+click.rich_click.OPTION_GROUPS = {
+    "darshan_summary": [
+        {
+            "name": "Basic usage",
+            "options": ["--log_path", "--output", "--help"],
+        },
+        {
+            "name": "Heatmap Options",
+            "options": ["--split-heatmaps", "--force-dxt"],
+        },
+    ],
+}
+
+
+@click.command()
+@click.option('--log_path', help='Path to darshan log file.', required=True)
+@click.option('--output', help='Specify output filename.')
+# TODO: actually implement heatmap options in summary report
+@click.option('--split-heatmaps',
+              is_flag=True,
+              show_default=True,
+              default=False,
+              help='Separate heatmaps for read and write IO activity.')
+@click.option('--force-dxt',
+              is_flag=True,
+              show_default=True,
+              default=False,
+              help='Force plotting of DXT heatmaps even when large.')
+def summary_report(log_path,
+                   output,
+                   split_heatmaps,
+                   force_dxt):
+    start = time.perf_counter()
+    if output is None:
+        # if no output is provided, use the log file
+        # name to create the output filename
+        log_filename = os.path.splitext(os.path.basename(log_path))[0]
+        report_filename = f"{log_filename}_report.html"
+    else:
+        report_filename = output
+
+    # collect the report data to feed into the template
+    report_data = ReportData(log_path=log_path)
+
+    with importlib_resources.path(darshan.cli, "base.html") as base_path:
+        # load a template object using the base template
+        template = Template(filename=str(base_path))
+        # render the base template
+        stream = template.render(report_data=report_data)
+        with open(report_filename, "w") as f:
+            # print a message so users know where to look for their report
+            save_path = os.path.join(os.getcwd(), report_filename)
+            click.echo(
+                f"Report generated successfully. \n"
+                f"Saving report at location: {save_path}"
+            )
+            # save the rendered html
+            f.write(stream)
+            end = time.perf_counter()
+            total_time_sec = end - start
+            click.echo(f"Report generation time (s): {total_time_sec:.2f}")

darshan-util/pydarshan/setup.py

@@ -86,4 +86,8 @@
                               "examples/example_logs/*",
                               "examples/darshan-graph/*",
                               "tests/input/*"]},
+                  entry_points={"console_scripts": [
+                      "darshan_summary = darshan.cli.darshan_summary:summary_report",
+                      ],
+                  },
 )