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.