"""Export PUDL table and field metadata to RST for use in documentation."""
import pathlib
import sys
from typing import TYPE_CHECKING
import click
if TYPE_CHECKING:
from pudl.logging_helpers import LogLevel
@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
),
)
[docs]
def main(
skip: list[str],
output: pathlib.Path,
docs_dir: pathlib.Path,
logfile: pathlib.Path | None,
loglevel: LogLevel,
) -> int:
"""Export PUDL table and field metadata to RST for use in documentation.
metadata_to_rst -s bad_table1 -s bad_table2 -d ./pudl/docs -o ./datadict.rst
"""
# Deferred to keep --help fast; see pudl/scripts/__init__.py for rationale.
import pudl.logging_helpers # noqa: PLC0415
from pudl.metadata.classes import Package # noqa: PLC0415
from pudl.metadata.resources import RESOURCE_METADATA # noqa: PLC0415
logger = pudl.logging_helpers.get_logger(__name__)
pudl.logging_helpers.configure_root_logger(logfile=logfile, loglevel=loglevel)
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=docs_dir, path=output)
return 0
if __name__ == "__main__":
sys.exit(main())
