Mermaid output: improve display of long comments

[dhimmel]

Excellent utility! I learned about it in Terraform in Depth book.

We set Column.comment on our SQLAlchemy columns.

These get added to the mermaid flowchart by

paracelsus/paracelsus/transformers/mermaid.py

Lines 42 to 43 in f473a57

	if column.comment:
	options.append(column.comment)

And output, when comments are long, is like:

I wonder if there are easy to address the legibility and aspect ratio issue of these long comments, like:

• option to disable the comment column
• using a markdown string for comments to enable word wrap

[tedivm]

This is a great feature request! I'll try to get to this, but if you wanted to make an attempt at this I'm super happy to review any PRs.

[dhimmel]

Okay let me give a PR a try.

Some experiments first. Here is a mermaid diagram where the comment is quoted to "enclose the unicode text"

erDiagram
  llm_completions {
    UUID id PK "Unique identifier ."
    VARCHAR(7) status "Status of the LLM completion."
    VARCHAR finish_reason "Finish reason from the LLM completion. This is not coded as an enum, because upstream documentation is lacking and the stability of the values is unknown."
    FLOAT cost_cents "Cost of the LLM completion in cents.,nullable"
}

Loading

Here is a mermaid diagram where the comment is quoted and backticked to "enclose the markdown text". Now in this GitHub issue and on https://mermaid.live/, the comment renders as "Unsupported markdown: codespan".

erDiagram
  llm_completions {
    UUID id PK "Unique identifier ."
    VARCHAR(7) status "Status of the LLM completion."
    VARCHAR finish_reason "`Finish reason from the LLM completion. This is not coded as an enum, because upstream documentation is lacking and the stability of the values is unknown.`"
    FLOAT cost_cents "Cost of the LLM completion in cents.,nullable"
}

Loading

Ah looking deeper at the marmiad entityRelationshipDiagram docs for "Attribute Keys and Comments":

markdown formatting and unicode is not supported for keys

It looks like line breaks can be included as newline characters or via <br> and that sort of works, but not really (creates new row):

erDiagram
  llm_completions {
    UUID id PK "Unique identifier ."
    VARCHAR(7) status "Status of the LLM completion."
    VARCHAR finish_reason "Finish reason from the LLM completion.<br>This is not coded as an enum, because upstream<br>documentation is lacking<br>and the stability of the values is unknown."
    FLOAT cost_cents "Cost of the LLM completion in cents.,nullable"
}

Loading

So possibly for paracelsus the best solution would be an option to exclude comments? @tedivm what do you think about the best solutions? Then I will PR.

[dhimmel]

I started thinking this is really an upstream issue where mermaid's entityRelationshipDiagram should do a better job displaying comments possibly with markdown or wrapping or supporting newlines in comments.

So I went with a simple --omit-comments flag in #34