Improved Admonitions

[ReenigneArcher]

Just a small improvement to admonitions, using fontawesome.

Inspiration for the colors and icons was taken from furo

Doxyfile

# custom aliases
ALIASES = ""
# fontawsome
ALIASES += "fa_icon{1}=<i class=\"\1\"></i>"
# admonitions
ALIASES += "_admonition{4|}=<dl class=\"\2\"><dt>@fa_icon{\3} \1</dt><dd>\4</dd></dl>"
# see: https://jothepro.github.io/doxygen-awesome-css/class_my_library_1_1_example.html#autotoc_md6
ALIASES += "admonition{2|}=@_admonition{\1 | todo | fa-solid fa-bars | \2}"
ALIASES += "attention{1}=@_admonition{Attention | bug | fa-solid fa-triangle-exclamation | \1}"
ALIASES += "caution{1}=@_admonition{Caution | section warning | fa-solid fa-triangle-exclamation | \1}"
ALIASES += "danger{1}=@_admonition{Danger | bug | fa-solid fa-circle-exclamation | \1}"
ALIASES += "error{1}=@_admonition{Error | bug | fa-solid fa-circle-xmark | \1}"
ALIASES += "hint{1}=@_admonition{Hint | section pre | fa-solid fa-circle-question | \1}"
ALIASES += "important{1}=@_admonition{Important | todo | fa-solid fa-fire | \1}"
ALIASES += "note{1}=@_admonition{Note | section note | fa-solid fa-pencil | \1}"
ALIASES += "seealso{1}=@_admonition{See also | section note | fa-solid fa-circle-info | \1}"
ALIASES += "tip{1}=@_admonition{Tip | section pre | fa-solid fa-circle-info | \1}"
ALIASES += "todo{1}=@_admonition{TODO | section deprecated | fa-solid fa-pencil | \1}"
ALIASES += "warning{1}=@_admonition{Warning | section warning | fa-solid fa-triangle-exclamation | \1}"

The install of fontawesome is a little tricky, because the directory structure cannot change (at least when using the npm version)

export READTHEDOCS_OUTPUT=docs/build/  # or wherever your docs build goes
npm install "@fortawesome/fontawesome-free"
mkdir -p ${READTHEDOCS_OUTPUT}html/assets/fontawesome/css
mkdir -p ${READTHEDOCS_OUTPUT}html/assets/fontawesome/js
cp node_modules/@fortawesome/fontawesome-free/css/all.min.css ${READTHEDOCS_OUTPUT}html/assets/fontawesome/css
cp node_modules/@fortawesome/fontawesome-free/js/all.min.js ${READTHEDOCS_OUTPUT}html/assets/fontawesome/js
cp -r node_modules/@fortawesome/fontawesome-free/webfonts ${READTHEDOCS_OUTPUT}html/assets/fontawesome/

And add this to your custom header.html

<!--FONTAWESOME START-->
<link href="$relpath^assets/fontawesome/css/all.min.css" rel="stylesheet" type="text/css" />
<script type="text/javascript" src="$relpath^assets/fontawesome/js/all.min.js"></script>
<!--FONTAWESOME END-->

This is pretty hacky, and there are probably better ways to achieve the same result. Open to feedback and improvements.

[trulko]

A CSS snippet like this added to the stylesheet likewise adds icons, though it does not extend the range of supported admonitions from the Doxygen default:

@import url("https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.5.0/css/all.min.css");
dl.section dt::before { font-family: "Font Awesome 6 Free" }
dl.section.note dt::before { content: "\f249\00a0" }
dl.section.remark dt::before { content: "\f05a\00a0"}
dl.section.warning dt::before { content: "\f071\00a0" }
dl.section.attention dt::before { content: "\f0a1\00a0" }

This does not require new aliases or installation (we get CSS-only Font Awesome from the CDN). Using the following Doxygen comments:

\note A note
\remark A remark
\warning A warning
\attention Something worth shouting about

The output looks like:

[ReenigneArcher]

Thanks for this! I ended up adding this in LizardByte/doxyconfig#36