Markdown emitters for TopMark config commands.
This module contains helpers that render human-facing output for config-related
commands in OutputFormat.MARKDOWN.
Notes
These helpers return strings and do not perform any I/O.
render_config_init_markdown
render_config_init_markdown(prepared)
Render topmark config init output as Markdown.
Parameters:
| Name |
Type |
Description |
Default |
prepared
|
ConfigInitHumanReport
|
Prepared TOML text and optional fallback error.
|
required
|
Returns:
| Type |
Description |
str
|
Markdown document string (with trailing newline).
|
Source code in src/topmark/presentation/markdown/config.py
| def render_config_init_markdown(
prepared: ConfigInitHumanReport,
) -> str:
"""Render `topmark config init` output as Markdown.
Args:
prepared: Prepared TOML text and optional fallback error.
Returns:
Markdown document string (with trailing newline).
"""
md: str = render_toml_markdown(
heading="Initial TopMark Configuration (TOML)",
heading_level=1,
toml_text=prepared.toml_text,
)
parts: list[str] = [
md,
]
if prepared.error is None:
return md
if prepared.error:
# Prepend a warning blockquote (keeps the TOML block unchanged)
warning: str = (
f"> **Warning:** falling back to synthesized default config: {prepared.error}\n\n"
)
parts.append(warning)
parts.append(render_version_footer_markdown())
return "\n".join(parts)
|
render_config_defaults_markdown
render_config_defaults_markdown(prepared)
Render topmark config defaults output as Markdown.
Parameters:
| Name |
Type |
Description |
Default |
prepared
|
ConfigDefaultsHumanReport
|
Prepared default configuration TOML (may include root = true).
|
required
|
Returns:
| Type |
Description |
str
|
Markdown document string (with trailing newline).
|
Source code in src/topmark/presentation/markdown/config.py
| def render_config_defaults_markdown(
prepared: ConfigDefaultsHumanReport,
) -> str:
"""Render `topmark config defaults` output as Markdown.
Args:
prepared: Prepared default configuration TOML (may include `root = true`).
Returns:
Markdown document string (with trailing newline).
"""
toml_md: str = render_toml_markdown(
heading="Default TopMark Configuration (TOML)",
heading_level=1,
toml_text=prepared.toml_text,
)
footer: str = render_version_footer_markdown()
return "\n".join(
[
toml_md,
footer,
]
)
|
render_config_check_markdown
render_config_check_markdown(prepared)
Render topmark config check output as Markdown.
Parameters:
| Name |
Type |
Description |
Default |
prepared
|
ConfigCheckHumanReport
|
Prepared human-facing data (files, optional TOML, diagnostics).
|
required
|
Returns:
| Type |
Description |
str
|
Markdown document string (with trailing newline).
|
Source code in src/topmark/presentation/markdown/config.py
| def render_config_check_markdown(
prepared: ConfigCheckHumanReport,
) -> str:
"""Render `topmark config check` output as Markdown.
Args:
prepared: Prepared human-facing data (files, optional TOML, diagnostics).
Returns:
Markdown document string (with trailing newline).
"""
lines: list[str] = []
lines.append("## topmark config check\n")
status: str = "OK" if prepared.ok else "FAILED"
counts: HumanDiagnosticCounts = prepared.counts
diags: list[HumanDiagnosticLine] = prepared.diagnostics
# Summary
lines.append("### Summary\n")
lines.append(f"- **Status:** {status}")
lines.append(f"- **Strict:** {str(prepared.strict).lower()}")
lines.append(f"- **Errors:** {counts.error}")
lines.append(f"- **Warnings:** {counts.warning}\n")
# Diagnostics
diag_md: str = render_human_diagnostics_markdown(
title="Diagnostics",
counts=counts,
diagnostics=diags,
)
if diag_md:
lines.append(diag_md.rstrip())
lines.append("")
# Config files
lines.append(f"### Config files processed ({len(prepared.config_files)})\n")
for i, p in enumerate(prepared.config_files, start=1):
lines.append(f"{i}. {p}")
lines.append("")
if prepared.merged_toml is not None:
lines.append("### Effective merged TOML\n")
lines.append("```toml")
lines.append(prepared.merged_toml.rstrip())
lines.append("```")
lines.append("")
lines.append(render_version_footer_markdown())
return "\n".join(lines).rstrip() + "\n"
|
render_config_dump_markdown
render_config_dump_markdown(prepared)
Render topmark config dump output as Markdown.
Parameters:
| Name |
Type |
Description |
Default |
prepared
|
ConfigDumpHumanReport
|
Prepared config dump data (files, flattened TOML, optional provenance).
|
required
|
Returns:
| Type |
Description |
str
|
Markdown document string (with trailing newline).
|
Source code in src/topmark/presentation/markdown/config.py
| def render_config_dump_markdown(
prepared: ConfigDumpHumanReport,
) -> str:
"""Render `topmark config dump` output as Markdown.
Args:
prepared: Prepared config dump data (files, flattened TOML, optional provenance).
Returns:
Markdown document string (with trailing newline).
"""
lines: list[str] = []
if prepared.show_config_layers and prepared.provenance_toml is not None:
lines.append(
render_toml_markdown(
heading="TopMark Config Provenance Layers (TOML)",
heading_level=1,
toml_text=prepared.provenance_toml,
).rstrip()
)
lines.append("")
lines.append("---")
lines.append("")
lines.append(
render_toml_markdown(
heading="TopMark Config Dump (Flattened TOML)",
heading_level=1,
toml_text=prepared.merged_toml,
).rstrip()
)
else:
lines.append(
render_toml_markdown(
heading="TopMark Config Dump (TOML)",
heading_level=1,
toml_text=prepared.merged_toml,
).rstrip()
)
lines.append("")
lines.append(f"### Config files processed ({len(prepared.config_files)})\n")
for i, p in enumerate(prepared.config_files, start=1):
lines.append(f"{i}. {p}")
lines.append(render_version_footer_markdown())
return "\n".join(lines).rstrip() + "\n"
|