trudag.publish

Library for creating written summaries of trustable software projects.

Report

Report(
    graph: TrustableGraph,
    project_name: str,
    output_path: Path,
    scores: dict[str, ItemScore],
    non_normative_body: bool = False,
    name_references_only=False,
    figures: bool = False,
    score_tables: bool = False,
    data_store_client: DataStoreClientProtocol
    | None = None,
    sensitivity: dict[str, dict[str, float]] | None = None,
    artifacts_published: dict[str, str] | None = None,
    root_report: bool = True,
)

The set of information defining a Trustable Report, writeable as markdown.

Parameters:

Name	Type	Description	Default
`graph`	`TrustableGraph`	Graph for the project	required
`project_name`	`str`	Name of the project	required
`output_path`	`Path`	Directory to write all generated files within.	required
`scores`	`dict[str, ItemScore]`	Dictionary of (item_str, confidence score) pairs	required
`non_normative_body`	`bool`	Include the body text of non-normative items. Defaults to False.	`False`
`name_references_only`	`bool`	Do not include the contents of external references. Defaults to False.	`False`
`figures`	`bool`	Include time series plots (requires data store).	`False`
`score_tables`	`bool`	Include historic store tables (requires data store)	`False`
`data_store_client`	`DataStoreClient`	Injectable DataStoreClient for testing.	`None`
`sensitivity`	`dict[str, dict[str, float]]`	Dictionary of item and their graph sensitivity values.	`None`
`artifacts_published`	`dict[str, str]`	Dictionary of artifact reference paths with their project names to be published.	`None`
`root_report`	`bool`	Flag to check if the report to be published is the report on the top most level.	`True`

write_navigation_index

write_navigation_index(
    report_name: str, document_map: dict[str, list[Item]]
) -> None

The Trustable Report's navigation as formatted markdown.

Parameters:

Name	Type	Description	Default
`report_name`	`str`	Trustable Report's file stem.	required

write_report

write_report() -> None

The Trustable Report as markdown.

create_markdown_table

create_markdown_table(
    headers: list[str],
    data: list[list[str | float]],
    widths: list[int] | None = None,
    line_break: bool = True,
    indent: int = 0,
) -> str

A helper function for creating markdown tables. widths[i] corresponds to the % width of column i.

publish

publish(
    graph: TrustableGraph,
    project_name: str,
    all_bodies: bool,
    output_path: Path,
    scores: dict[str, ItemScore],
    figures: bool = False,
    score_tables: bool = False,
    data_store_client: DataStoreClientProtocol
    | None = None,
    sensitivity: dict[str, dict[str, float]] | None = None,
    artifacts_published: dict[str, str] | None = None,
    root_report: bool = True,
) -> None

Given a trustable graph in cwd, summarise the graph (and its trustable score) in the markdown file "trustable_report_for_" + project_name + ".md".

Also produce an item summary and nav file.

Parameters:

Name	Type	Description	Default
`graph`	`Graph`	Graph to summarise	required
`project_name`	`str`	Name of the trustable software project.	required
`all_bodies`	`bool`	Include the body text of all (i.e. including non-normative) items in the generated markdown.	required
`output_path`	`Path`	Directory to write all generated files within.	required
`scores`	`dict[str, float]`	Dictionary of (item_str, confidence score) pairs	required
`figures`	`bool`	Include time series plots (requires data store)	`False`
`score_tables`	`bool`	Include historic store tables (requires data store)	`False`
`data_store_client`	`DataStoreClient`	Injectable DataStoreClient for testing	`None`