[Request] How to document descriptions, containing markdown? asciidoc? Description as code? escaping code blocks?

[aisbergde]

Is your feature request related to a problem? Please describe.

Currently, my descriptions in ms_descriptions are in Markdown, because I tried to use SchemaSpy to document databases. And I tried SchemaSpy it because it supports markdown in descriptions.

Now I tried to document these databases with sp_doc, but the result in unusable when I include to document the ms_description: The markdown from the descriptions interfere with the generated markdown.

I don't know if it would be possible to "nest" markdown. But I am afraid, this is not possible. But maybe there could be an option to keep the content of the markdown descriptions as they are, but to mark them as code?

Of course there are also code blocks inside the markdown descriptions, and it looks like this will not work, because markdown has no clear syntax to mark the end of some code block:

## markdown description

bla bla bla

select a
from b

and some line after the code

I could use a language marker for the inner code, but again, markdown interpreter will not find detect this as nested code.

## markdown description

bla bla bla

```sql
select a
from b

and some line after the code

Describe the solution you'd like

• An alternative would be an option to generate asciidoc files as an alternative to markdown.
  The Syntax would allow nested code, GitHub and some other sites support not only markdown, but also asciidoc.
• An option to include the description as code could help.
  If not using code blocks in the description then the outer usage of code block could work.
  • Maybe the code marker could be "escaped" in any useful way. It looks note fine, but it would not interfere with the main part of the documentation:

## markdown description

bla bla bla

'```
select a
from b
'``` 

and some line after the code

Describe alternatives you've considered

To exclude the descriptions from documentation. But it makes no sense to have a full documentation in markdown in the descriptions and not to use it.

[lowlydba]

An alternative would be an option to generate asciidoc files as an alternative to markdown.

I am not too familiar with asciidoc, but I did hope to eventually expand into a few other markdown-adjacent formats. This would be a fairly big lift, though.

An option to include the description as code could help.

This is an attractive short-term fix, I think. I'm not sure the formatting would look great but it is probably an improvement over current state.

Maybe the code marker could be "escaped" in any useful way.

Using a slash should do the trick here, i.e.

\```

which shows up as

```

to escape the code block.

[lowlydba]

After some tinkering, the following approach should work:

• If EP is in a table, replace all line breaks with <br/> tag to retain line spacing and cause it to render as plain text, preventing breaking of the table
• If EP is out of table, use lots (5?) of backticks to make a high level code block that the markdown can be nested in, to prevent it from breaking the visual flow of the document

I'll add these enhancements under this ticket, but @aisbergde if you could create a new issue just for the asciidoc enhancement for later consideration, I'd appreciate it.

[lowlydba]

@aisbergde Could you try using the development branch and see if your issues are resolved?

You should be able to see the markdown display as plain text. The only caveat is that any | characters in code blocks in EP markdown will show up as the HTML code for a pipe.

[aisbergde]

@lowlydba it is better now, descriptions are inside descriptions. But there are some issues with <br\> on combination with code blocks

normally this works:

| SignPrev_03Month | INT | no |  |  | CASE <br/>WHEN Date > CurrentDate  THEN 1<br/>WHEN [Date_plus_03M] > CurrentDate THEN 0<br/>ELSE -1<br/>END |
| SignPrev_06Month | INT | no |  |  | CASE <br/>WHEN Date > CurrentDate  THEN 1<br/>WHEN [Date_plus_06M] > CurrentDate THEN 0<br/>ELSE -1<br/>END |
| SignPrev_09Month | INT | no |  |  | CASE <br/>WHEN Date > CurrentDate  THEN 1<br/>WHEN [Date_plus_09M] > CurrentDate THEN 0<br/>ELSE -1<br/>END |

But in combination with code blocks it doesn't work so good:

example

| Current_YTD | INT | no |  |  | ```sql<br/>IIF(IsCurrentYear = 1 and [Date] <= CurrentDate, 1, 0)<br/>```<br/> |
| Current_YTpM | INT | no |  |  | ```sql<br/>/* YTpM - Year To prev Month*/<br/>IIF(IsCurrentYear = 1 <br/>and [Date] < Current_FirstDayOfMonth<br/>, 1, 0)<br/>```<br/> |

I tried several workarounds, one way would be to replace "```" by "´´´"

| yyyymmdd_int | INT | yes |  |  |  YEAR(Date) * 10000 + MONTH(Date) * 100 + DAY(Date) |
| Current_YTD | INT | no |  |  | ´´´sql<br/>IIF(IsCurrentYear = 1 and [Date] <= CurrentDate, 1, 0)<br/>´´´<br/> |
| Current_YTpM | INT | no |  |  | ´´´sql<br/>/* YTpM - Year To prev Month*/<br/>IIF(IsCurrentYear = 1 <br/>and [Date] < Current_FirstDayOfMonth<br/>, 1, 0)<br/>´´´<br/> |
| Current_YTpM_special | INT | no |  |  | ´´´sql<br/>/*<br/>YTpM - Year To prev Month<br/>31.12. of last year is additional added<br/>and 31.12. of current year is not included */<br/>IIF(<br/>(IsCurrentYear = 1 OR [date] = Current_LastDayOfPrevYear)<br/>and [Date] < Current_FirstDayOfMonth<br/>and [date] < Current_LastDayOfYear<br/>, 1, 0)<br/>´´´<br/> |
| FirstDayOfNextMonth | DATE | yes |  |  | ´´´sql<br/>DATEADD(Month, 1, FirstDayOfMonth)<br/>´´´<br/> |

[lowlydba]

Thanks so much for the detailed feedback!

I think using the html character code for the ticks (|) may be a quick solution (same as how pipes are formatted now) and should fix it without having to reverse the ticks. If not, reversing the ticks will be the backup strategy 👍🏻

I will have some new changes pushed soon 🚀

[lowlydba]

@aisbergde I have an updated version on the development branch now, if you would like to test it out. It should address the latest issues.

[aisbergde]

@lowlydba perfect!

Excellent support! Makes me want to open a few more feature requests :-)