From 6a47403bdc46963b4bcf4a32440c13040663eee5 Mon Sep 17 00:00:00 2001 From: ReenigneArcher <42013603+ReenigneArcher@users.noreply.github.com> Date: Thu, 3 Sep 2026 13:40:56 -0400 Subject: [PATCH] docs(source_code): reformat examples into code/result tables Convert admonition and custom alias examples in `docs/source_code.md` from bullet-style snippets into side-by-side Code/Result tables for clearer documentation. Add `code-result-table` styles in `doxyconfig.css` to enforce full-width fixed layout and top-aligned 50/50 table cells. --- docs/source_code.md | 441 ++++++++++++++++++++++++++++++++++++-------- doxyconfig-Doxyfile | 4 +- doxyconfig.css | 10 + 3 files changed, 372 insertions(+), 83 deletions(-) diff --git a/docs/source_code.md b/docs/source_code.md index 1bc9484..2f5d13a 100644 --- a/docs/source_code.md +++ b/docs/source_code.md @@ -100,60 +100,151 @@ enum class MyEnum #### Standard Admonitions -* @verbatim@attention Attention needed.@endverbatim - @attention Attention needed. - -* @verbatim@important An important message.@endverbatim - @important An important message. - -* @verbatim@note A note.@endverbatim - @note A note. - -* @verbatim@pre A precondition.@endverbatim - @pre A precondition. - -* @verbatim@remark Some remarks.@endverbatim - @remark Some remarks. - -* @verbatim@warning - A warning.@endverbatim - @warning A warning. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CodeResult
+@verbatim +@attention Attention needed. +@endverbatim + +@attention Attention needed. +
+@verbatim +@important An important message. +@endverbatim + +@important An important message. +
+@verbatim +@note A note. +@endverbatim + +@note A note. +
+@verbatim +@pre A precondition. +@endverbatim + +@pre A precondition. +
+@verbatim +@remark Some remarks. +@endverbatim + +@remark Some remarks. +
+@verbatim +@warning A warning. +@endverbatim + +@warning A warning. +
#### GitHub Flavored Markdown Admonitions -* @verbatim + + + + + + + + + + + + + + + + + + + + + + + + + +
CodeResult
+@verbatim > [!CAUTION] > This is a caution. @endverbatim - > [!CAUTION] - > This is a caution. + + +> [!CAUTION] +> This is a caution. -* @verbatim +
+@verbatim > [!IMPORTANT] > This is important. @endverbatim - > [!IMPORTANT] - > This is important. + + +> [!IMPORTANT] +> This is important. -* @verbatim +
+@verbatim > [!NOTE] > This is a note. @endverbatim - > [!NOTE] - > This is a note. + -* @verbatim +> [!NOTE] +> This is a note. + +
+@verbatim > [!TIP] > This is a tip. @endverbatim - > [!TIP] - > This is a tip. + -* @verbatim +> [!TIP] +> This is a tip. + +
+@verbatim > [!WARNING] > This is a warning. @endverbatim - > [!WARNING] - > This is a warning. + + +> [!WARNING] +> This is a warning. + +
### Custom Aliases @@ -161,61 +252,249 @@ We have defined some custom aliases to simplify documenting examples. * \@examples - Start of an example block. This will format the following text as `cpp`. * \@examples_end - End of an example block. -* \@lucide_icon{icon name} - Insert a Lucide icon. Give the icon name as an argument. - e.g. \@lucide_icon{check}. -* Admonitions - * \@admonition{Custom Title | Content } - @admonition{The one with the custom titles | It’s got a certain charm to it.} - * \@attention{Content} - @attention{The sun causes global warming.} - * \@caution{Content} - @caution{Cliff ahead: Don’t drive off it.} - * \@danger{Content} - @danger{Mad scientist at work!} - * \@error{Content} - @error{Does not compute.} - * \@hint{Content} - @hint{Insulators insulate, until they are subject to ______ voltage.} - * \@important{Content} - @important{Tech is not neutral, nor is it apolitical.} - * \@note{Content} - @note{This is a note.} - * \@seealso{Content} - @seealso{Other relevant information.} - * \@tip{Content} - @tip{25% if the service is good.} - * \@todo{Content} - @todo{Fix this.} - * \@warning{Content} - @warning{Reader discretion is strongly advised.} - -* Markers - * \@red{Content}
- @red{This is red.} - * \@blue{Content}
- @blue{This is blue.} - * \@green{Content}
- @green{This is green.} - * \@yellow{Content}
- @yellow{This is yellow.} - -* Expander - @verbatim - @expander{Expander Title | Expander Content} - @endverbatim - @expander{Expander Title | Expander Content} -* Tabs - @verbatim +#### Lucide Icons + +Use `\@lucide_icon{icon name}` to insert a Lucide icon. + + + + + + + + + + +
CodeResult
+@verbatim +@lucide_icon{check} +@endverbatim + +@lucide_icon{check} +
+ +#### Admonitions + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CodeResult
+@verbatim +@admonition{Custom Title | Content} +@endverbatim + +@admonition{The one with the custom titles | It’s got a certain charm to it.} +
+@verbatim +@attention{Content} +@endverbatim + +@attention{The sun causes global warming.} +
+@verbatim +@caution{Content} +@endverbatim + +@caution{Cliff ahead: Don’t drive off it.} +
+@verbatim +@danger{Content} +@endverbatim + +@danger{Mad scientist at work!} +
+@verbatim +@error{Content} +@endverbatim + +@error{Does not compute.} +
+@verbatim +@hint{Content} +@endverbatim + +@hint{Insulators insulate, until they are subject to ______ voltage.} +
+@verbatim +@important{Content} +@endverbatim + +@important{Tech is not neutral, nor is it apolitical.} +
+@verbatim +@note{Content} +@endverbatim + +@note{This is a note.} +
+@verbatim +@seealso{Content} +@endverbatim + +@seealso{Other relevant information.} +
+@verbatim +@tip{Content} +@endverbatim + +@tip{25% if the service is good.} +
+@verbatim +@todo{Content} +@endverbatim + +@todo{Fix this.} +
+@verbatim +@warning{Content} +@endverbatim + +@warning{Reader discretion is strongly advised.} +
+ +#### Markers + + + + + + + + + + + + + + + + + + + + + + +
CodeResult
+@verbatim +@red{Content} +@endverbatim + +@red{This is red.} +
+@verbatim +@blue{Content} +@endverbatim + +@blue{This is blue.} +
+@verbatim +@green{Content} +@endverbatim + +@green{This is green.} +
+@verbatim +@yellow{Content} +@endverbatim + +@yellow{This is yellow.} +
+ +#### Expander + + + + + + + + + + +
CodeResult
+@verbatim +@expander{Expander Title | Expander Content} +@endverbatim + +@expander{Expander Title | Expander Content} +
+ +#### Tabs + + + + + + + + + + +
CodeResult
+@verbatim @tabs{ @tab{ Tab 1 Title | Tab 1 Content } @tab{ Tab 2 Title | Tab 2 Content } } @endverbatim - @tabs{ - @tab{ Tab 1 Title | Tab 1 Content } - @tab{ Tab 2 Title | Tab 2 Content } - } + +@tabs{ + @tab{ Tab 1 Title | Tab 1 Content } + @tab{ Tab 2 Title | Tab 2 Content } +} +
diff --git a/doxyconfig-Doxyfile b/doxyconfig-Doxyfile index d3e344e..f66dbbe 100644 --- a/doxyconfig-Doxyfile +++ b/doxyconfig-Doxyfile @@ -76,8 +76,8 @@ ALIASES += "todo{1}=@_admonition{TODO | section deprecated | pencil | \1}" ALIASES += "warning{1}=@_admonition{Warning | section warning | triangle-alert | \1}" # tabs # see: https://github.com/jothepro/doxygen-awesome-css/discussions/146 -ALIASES += tab{2|}="@htmlonly
  • @endhtmlonly^^\1^^@htmlonly@endhtmlonly^^\2^^@htmlonly
    • @endhtmlonly" -ALIASES += tabs{1}="@htmlonly

    @endhtmlonly" +ALIASES += tab{2|}="
  • \1^^\2^^
    • " +ALIASES += tabs{1}="

    " # markers ALIASES += red{1}="\1" ALIASES += blue{1}="\1" diff --git a/doxyconfig.css b/doxyconfig.css index 9317dc8..700ce61 100644 --- a/doxyconfig.css +++ b/doxyconfig.css @@ -43,6 +43,16 @@ dl.important dt { color: var(--todo-color-dark); } +table.code-result-table { + table-layout: fixed; + width: 100%; +} + +table.code-result-table td { + vertical-align: top; + width: 50%; +} + /* Live search dropdown */ #RTDLiveResults { display: none;