trudag.publish

Library for creating written summaries of trustable software projects.

MarkdownPublisher

MarkdownPublisher(
    graph: TrustableGraph,
    configuration: TrustableOptions,
    scores: dict[str, ItemScore] | None = None,
    sensitivity_data: dict[str, dict[str, float]]
    | None = None,
    data_store_client: DataStoreClientProtocol
    | None = None,
    artifacts_published: dict[str, str] | None = None,
    root_report: bool = True,
)

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

Also produce an item summary and nav file.

Parameters:

Name	Type	Description	Default
`graph`	`Graph`	Graph to summarise	required
`configuration`	`TrustableOptions`	Configuration containing the project configuration options for publishing report(s).	required
`scores`	`dict[str, ItemScore] \| None`	Dictionary of items and their scores.	`None`
`sensitivity_data`	`dict[str, dict[str, float]] \| None`	Dictionary of items and their sensitivity analysis.	`None`
`data_store_client`	`DataStoreClient`	Injectable DataStoreClient for testing	`None`
`artifacts_published`	`dict[str, str] \| None`	Dictionary of project_name with their artifacts being passed when dealing with artifact references.	`None`
`root_report`	`bool`	True if the report to be published is the main report or False if it is an artifact reference report being published.	`True`

Report

Report(
    graph: TrustableGraph,
    report_configuration: ReportOptions,
    scoring_configuration: ScoringOptions,
    scores: dict[str, ItemScore],
    output_path: Path,
    data_store_client: DataStoreClientProtocol
    | None = None,
    sensitivity_data: 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.	required
`name_references_only`	`bool`	Do not include the contents of external references. Defaults to False.	required
`figures`	`bool`	Include time series plots (requires data store).	required
`score_tables`	`bool`	Include historic store tables (requires data store)	required
`data_store_client`	`DataStoreClient`	Injectable DataStoreClient for testing.	`None`
`sensitivity`	`dict[str, dict[str, float]]`	Dictionary of item and their graph sensitivity values.	required
`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.

mk_markdown_table

mk_markdown_table(
    table_data: dict[str, list[tuple[int, str] | list]],
    line_break: bool = True,
    indent: int = 0,
) -> str

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