API reference

Plugin registration

CWL to Markdown Transpiler-Mate Plugin.

Source code in src/cwl2markdown/plugin.py

@transpiler_plugin(
    name="cwl2markdown",
    description="CWL to Markdown Transpiler-Mate Plugin.",
    options_model=CWL2MarkdownOptions,
)
def cwl2markdown(context: TranspilerContext, options: CWL2MarkdownOptions) -> None:
    """CWL to Markdown Transpiler-Mate Plugin."""
    _jinja_environment = Environment(
        loader=PackageLoader(package_name="cwl2markdown"),
        autoescape=select_autoescape(),
    )
    _jinja_environment.globals["type_to_string"] = type_to_string
    _jinja_environment.filters.update(
        _to_mapping(
            [
                get_exection_command,
                normalize_author,
                normalize_contributor,
            ]
        )
    )
    _jinja_environment.tests.update(_to_mapping([nullable]))

    template = _jinja_environment.get_template("index.md")

    try:
        options.output.mkdir(parents=True, exist_ok=True)

        for workflow in context.get_processes_by_type(
            Workflow, [context.process_id] if context.process_id else None
        ):
            target: Path = Path(options.output, f"{workflow.id}.md")
            logger.info(f"Rendering Markdown documentation to {target.absolute()}...")

            with target.open("w") as output_stream:
                output_stream.write(
                    template.render(
                        version=_get_version(),
                        timestamp=datetime.fromtimestamp(time.time()).isoformat(
                            timespec="milliseconds"
                        ),
                        software_application=context.metadata,
                        workflow=workflow,
                        index=context.document,
                    )
                )
            logger.success(
                f"Markdown documentation successfully serialized to {target.absolute()}"
            )
    except Exception as e:
        raise PluginExecutionError(
            f"An error occurred when serializing to {options.output.absolute()}, see nested exception"
        ) from e

Options

Bases: BaseModel

Options accepted by the CWL 2 Markdown plugin.

Source code in src/cwl2markdown/plugin.py

class CWL2MarkdownOptions(BaseModel):
    """Options accepted by the CWL 2 Markdown plugin."""

    model_config = ConfigDict(extra="forbid")

    output: Annotated[
        Path, Field(default=Path("./"), description="The output directory path")
    ]

Template helpers

Return application authors as role models for template rendering.

Source code in src/cwl2markdown/plugin.py

def normalize_author(
    software_application: SoftwareApplication,
) -> list[AuthorRole]:
    """Return application authors as role models for template rendering."""
    authors = software_application.author
    author_list = authors if isinstance(authors, list) else [authors]
    return [
        author
        if isinstance(author, AuthorRole)
        else AuthorRole(role_name=NA_ROLE, author=author)
        for author in author_list
    ]

Return application contributors as role models for template rendering.

Source code in src/cwl2markdown/plugin.py

def normalize_contributor(
    software_application: SoftwareApplication,
) -> list[ContributorRole]:
    """Return application contributors as role models for template rendering."""
    contributors = software_application.contributor
    if contributors is None:
        return []

    contributor_list = (
        contributors if isinstance(contributors, list) else [contributors]
    )
    return [
        contributor
        if isinstance(contributor, ContributorRole)
        else ContributorRole(role_name=NA_ROLE, contributor=contributor)
        for contributor in contributor_list
    ]