From b00462ff04fe8570c1f8b06ab5565deb7f7d789b Mon Sep 17 00:00:00 2001
From: Zane Selvans <zane.selvans@catalyst.coop>
Date: Sat, 2 Dec 2023 13:52:04 -0600
Subject: [PATCH] Migrate metadata_to_rst to use Click framework.

---
 pyproject.toml                      |   2 +-
 src/pudl/convert/metadata_to_rst.py | 124 ++++++++++++++++------------
 2 files changed, 72 insertions(+), 54 deletions(-)

diff --git a/pyproject.toml b/pyproject.toml
index 5bda778938..1fef9954e7 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -119,7 +119,7 @@ keywords = [
 ]
 
 [project.scripts]
-metadata_to_rst = "pudl.convert.metadata_to_rst:main"
+metadata_to_rst = "pudl.convert.metadata_to_rst:metadata_to_rst"
 ferc_to_sqlite = "pudl.ferc_to_sqlite.cli:main"
 pudl_datastore = "pudl.workspace.datastore:main"
 pudl_etl = "pudl.etl.cli:pudl_etl"
diff --git a/src/pudl/convert/metadata_to_rst.py b/src/pudl/convert/metadata_to_rst.py
index 4e92453a09..372407330c 100644
--- a/src/pudl/convert/metadata_to_rst.py
+++ b/src/pudl/convert/metadata_to_rst.py
@@ -1,8 +1,9 @@
 """Export PUDL table and field metadata to RST for use in documentation."""
 
-import argparse
+import pathlib
 import sys
-from pathlib import Path
+
+import click
 
 import pudl.logging_helpers
 from pudl.metadata.classes import Package
@@ -11,64 +12,81 @@
 logger = pudl.logging_helpers.get_logger(__name__)
 
 
-def parse_command_line(argv):
-    """Parse command line arguments. See the -h option.
-
-    Args:
-        argv (str): Command line arguments, including caller filename.
+@click.command(
+    context_settings={"help_option_names": ["-h", "--help"]},
+)
+@click.option(
+    "--skip",
+    "-s",
+    help=(
+        "Name of a table that should be skipped and excluded from RST output. "
+        "Use this option multiple times to skip multiple tables."
+    ),
+    type=str,
+    default=[],
+    multiple=True,
+)
+@click.option(
+    "--output",
+    "-o",
+    type=click.Path(),
+    default=None,
+    help="Path to which the RST output should be written. Defaults to STDOUT.",
+)
+@click.option(
+    "--docs-dir",
+    "-d",
+    type=click.Path(
+        exists=True,
+        dir_okay=True,
+        file_okay=False,
+        resolve_path=True,
+        path_type=pathlib.Path,
+        writable=True,
+    ),
+    default=pathlib.Path().cwd() / "docs",
+    help=(
+        "Path to the PUDL repository docs directory. "
+        "Must exist and be writable. Defaults to ./docs/"
+    ),
+)
+@click.option(
+    "--logfile",
+    help="If specified, write logs to this file.",
+    type=click.Path(
+        exists=False,
+        resolve_path=True,
+        path_type=pathlib.Path,
+    ),
+)
+@click.option(
+    "--loglevel",
+    default="INFO",
+    type=click.Choice(
+        ["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"], case_sensitive=False
+    ),
+)
+def metadata_to_rst(
+    skip: list[str],
+    output: pathlib.Path,
+    docs_dir: pathlib.Path,
+    logfile: pathlib.Path,
+    loglevel: str,
+):
+    """Export PUDL table and field metadata to RST for use in documentation.
 
-    Returns:
-        dict: Dictionary of command line arguments and their parsed values.
+    metadata_to_rst -s bad_table1 -s bad_table2 -d ./pudl/docs -o ./datadict.rst
     """
-    parser = argparse.ArgumentParser(description=__doc__)
-    parser.add_argument(
-        "--skip",
-        help="List of table names that should be skipped and excluded from RST output.",
-        nargs="*",
-        default=[],
-    )
-    parser.add_argument(
-        "-o",
-        "--output",
-        help="Path to the file where the RST output should be written.",
-        default=False,
-    )
-    parser.add_argument(
-        "--docs_dir",
-        help="Path to docs directory.",
-        type=lambda x: Path(x).resolve(),
-        default=Path().cwd() / "docs",
-    )
-    parser.add_argument(
-        "--logfile",
-        default=None,
-        type=str,
-        help="If specified, write logs to this file.",
-    )
-    parser.add_argument(
-        "--loglevel",
-        help="Set logging level (DEBUG, INFO, WARNING, ERROR, or CRITICAL).",
-        default="INFO",
-    )
-    arguments = parser.parse_args(argv[1:])
-    return arguments
-
-
-def main():
-    """Run conversion from json to rst."""
-    args = parse_command_line(sys.argv)
-    pudl.logging_helpers.configure_root_logger(
-        logfile=args.logfile, loglevel=args.loglevel
-    )
+    pudl.logging_helpers.configure_root_logger(logfile=logfile, loglevel=loglevel)
 
-    logger.info(f"Exporting PUDL metadata to: {args.output}")
-    resource_ids = [rid for rid in sorted(RESOURCE_METADATA) if rid not in args.skip]
+    logger.info(f"Exporting PUDL metadata to: {output}")
+    resource_ids = [rid for rid in sorted(RESOURCE_METADATA) if rid not in skip]
     package = Package.from_resource_ids(resource_ids=tuple(sorted(resource_ids)))
     # Sort fields within each resource by name:
     for resource in package.resources:
         resource.schema.fields = sorted(resource.schema.fields, key=lambda x: x.name)
-    package.to_rst(docs_dir=args.docs_dir, path=args.output)
+    package.to_rst(docs_dir=docs_dir, path=output)
 
 
 if __name__ == "__main__":
-    sys.exit(main())
+    sys.exit(metadata_to_rst())