Doctools

Provides tools to assist with generating documentation for SSVC decision points.

Writes the following files for each decision point: - a json example that can be used in the decision point documentation

Examples

To generate the documentation for the decision points, use the following command:

python -m ssvc.doctools --overwrite --datadir ./tmp/json_out`

To regenerate the existing docs, use the following command:

python -m ssvc.doctools --overwrite --datadir data

EnsureDirExists

A runtime context that ensures that a directory exists or creates it otherwise.

Example:

with EnsureDirExists(dir):
    assert os.path.exists(dir)

Source code in src/ssvc/doctools.py

class EnsureDirExists:
    """
    A runtime context that ensures that a directory exists or creates it otherwise.

    Example:

        with EnsureDirExists(dir):
            assert os.path.exists(dir)
    """

    def __init__(self, dir: str):
        """
        Create a new EnsureDirExists context.

        Args:
            dir (str): The directory to ensure exists.

        Returns:
            EnsureDirExists: The new EnsureDirExists context.
        """
        self.dir = dir

    def __enter__(self):
        os.makedirs(self.dir, exist_ok=True)

    def __exit__(self, exc_type, exc_val, exc_tb):
        pass

__init__(dir)

Create a new EnsureDirExists context.

Parameters:

Name	Type	Description	Default
dir	str	The directory to ensure exists.	required

Returns:

Name	Type	Description
EnsureDirExists		The new EnsureDirExists context.

Source code in src/ssvc/doctools.py

def __init__(self, dir: str):
    """
    Create a new EnsureDirExists context.

    Args:
        dir (str): The directory to ensure exists.

    Returns:
        EnsureDirExists: The new EnsureDirExists context.
    """
    self.dir = dir

dump_decision_point(jsondir, dp, overwrite)

Generate the markdown table, json example, and markdown table file for a decision point.

Parameters:

Name	Type	Description	Default
jsondir	str	The directory to write the json example to.	required
outdir	str	The directory to write the markdown table file to.	required
dp	SsvcDecisionPoint	The decision point to generate documentation for.	required
overwrite	bool	Whether to overwrite existing files.	required

Returns:

Name	Type	Description
dict	None	A dictionary with the following keys: - include_file: The path to the markdown table file. - symlink: The path to the symlink that points to the markdown table file. - json_file: The path to the json example file.

Source code in src/ssvc/doctools.py

def dump_decision_point(
    jsondir: str, dp: SsvcDecisionPoint, overwrite: bool
) -> None:
    """
    Generate the markdown table, json example, and markdown table file for a decision point.

    Args:
        jsondir (str): The directory to write the json example to.
        outdir (str): The directory to write the markdown table file to.
        dp (SsvcDecisionPoint): The decision point to generate documentation for.
        overwrite (bool): Whether to overwrite existing files.

    Returns:
        dict: A dictionary with the following keys:
            - include_file: The path to the markdown table file.
            - symlink: The path to the symlink that points to the markdown table file.
            - json_file: The path to the json example file.
    """
    # make dp.name safe for use in a filename
    basename = filename_friendly(dp.name) + f"_{filename_friendly(dp.version)}"
    # - generate json example
    dump_json(basename, dp, jsondir, overwrite)

dump_json(basename, dp, jsondir, overwrite)

Generate the json example for a decision point.

Parameters:

Name	Type	Description	Default
basename	str	The basename of the json example file.	required
dp	SsvcDecisionPoint	The decision point to generate documentation for.	required
jsondir	str	The directory to write the json example to.	required
overwrite	bool	Whether to overwrite existing files.	required

Returns:

Name	Type	Description
str	str	The path to the json example file.

Source code in src/ssvc/doctools.py

def dump_json(
    basename: str, dp: DecisionPoint, jsondir: str, overwrite: bool
) -> str:
    """
    Generate the json example for a decision point.

    Args:
        basename (str): The basename of the json example file.
        dp (SsvcDecisionPoint): The decision point to generate documentation for.
        jsondir (str): The directory to write the json example to.
        overwrite (bool): Whether to overwrite existing files.

    Returns:
        str: The path to the json example file.
    """
    # if namespace is ssvc, it goes in jsondir
    filename = f"{basename}.json"
    parts = [
        jsondir,
    ]
    parts.append(filename_friendly(dp.namespace))
    dirname = os.path.join(*parts)

    parts.append(filename)

    json_file = os.path.join(*parts)

    if overwrite:
        remove_if_exists(json_file)
    with EnsureDirExists(dirname):
        try:
            logger.info(f"Writing {json_file}")
            with open(json_file, "x") as f:
                f.write(dp.model_dump_json(indent=2))
                f.write("\n")  # newline at end of file
        except FileExistsError:
            logger.warning(
                f"File {json_file} already exists, use --overwrite to replace"
            )
    return str(json_file)

find_modules_to_import(directory='../decision_points', package='ssvc.decision_points')

Find all modules that contain decision points and import them.

This is necessary to ensure that all decision points are registered.

Source code in src/ssvc/doctools.py

def find_modules_to_import(
    directory: str = "../decision_points",
    package: str = "ssvc.decision_points",
) -> bool:
    """
    Find all modules that contain decision points and import them.

    This is necessary to ensure that all decision points are registered.
    """
    imported_modules = []
    for root, _, files in os.walk(os.path.abspath(directory)):
        for file in files:
            if file.endswith(".py") and not file.startswith("__"):
                # build the module name relative to the package
                relative_path = os.path.relpath(root, directory)
                module_name = os.path.join(relative_path, file[:-3]).replace(
                    os.sep, "."
                )

                full_module_name = f"{package}.{module_name}"
                # import the module
                try:
                    logger.info(f"Importing module {full_module_name}")
                    module = importlib.import_module(full_module_name)
                    imported_modules.append(module)
                except ImportError as e:
                    logger.error(f"Failed to import {full_module_name}: {e}")
    return imported_modules

main()

Generate the json examples for decision points and decision tables.

Emits the following files: - json examples for each decision point in datadir/json/decision_points// - json examples for each decision table in datadir/json/decision_tables// - csv examples for each decision table in datadir/csv// - the ssvc object registry in datadir/json/ssvc_object_registry.json - the json schemas for decision points, decision tables, selection lists, and the registry in datadir/schema/v2/

Source code in src/ssvc/doctools.py

def main():
    """Generate the json examples for decision points and decision tables.

    Emits the following files:
    - json examples for each decision point in datadir/json/decision_points/<namespace>/
    - json examples for each decision table in datadir/json/decision_tables/<namespace>/
    - csv examples for each decision table in datadir/csv/<namespace>/
    - the ssvc object registry in datadir/json/ssvc_object_registry.json
    - the json schemas for decision points, decision tables, selection lists, and the registry in datadir/schema/v2/
    """

    import argparse

    parser = argparse.ArgumentParser(
        description="Generate json, json schema, and csv examples for SSVC Decision Points and Decision Tables"
    )
    parser.add_argument(
        "--overwrite",
        action="store_true",
        help="overwrite existing files",
        default=False,
    )

    parser.add_argument(
        "--datadir", help="json output directory", default="./tmp"
    )
    args = parser.parse_args()

    overwrite = args.overwrite
    jsondir = os.path.join(os.path.abspath(args.datadir), "json")
    csvdir = os.path.join(os.path.abspath(args.datadir), "csv")

    dp_dir = os.path.join(os.path.abspath(jsondir), "decision_points")
    dt_dir = os.path.join(os.path.abspath(jsondir), "decision_tables")

    find_modules_to_import(
        "./src/ssvc/decision_points", "ssvc.decision_points"
    )
    find_modules_to_import("./src/ssvc/outcomes", "ssvc.outcomes")
    find_modules_to_import(
        "./src/ssvc/decision_tables", "ssvc.decision_tables"
    )

    registry = get_registry()

    # for each decision point:
    for dp in get_all("DecisionPoint", registry=registry):
        dump_decision_point(dp_dir, dp, overwrite)

    # for each decision table:
    for dt in get_all("DecisionTable", registry=registry):
        dump_decision_table(dt_dir, dt, overwrite)
        dump_decision_table_csv(csvdir, dt, overwrite)

    # dump the registry
    registry_json = os.path.join(jsondir, "ssvc_object_registry.json")
    if overwrite:
        remove_if_exists(registry_json)
    with EnsureDirExists(jsondir):
        try:
            logger.info(f"Writing {registry_json}")
            with open(registry_json, "x") as f:
                f.write(registry.model_dump_json(indent=2, exclude_none=True))
                f.write("\n")  # newline at end of file
        except FileExistsError:
            logger.warning(
                f"File {registry_json} already exists, use --overwrite to replace"
            )

    dump_schemas(jsondir)