documentation: Modernize custom macros

Convert our custom macros to output asciidoctor instead of raw html,
silencing 6500 warnings. This will enable us to turn verbose builds
on, which will enable us to actually understand what is going on in
the doc tree.

Reviewed by: dch, kevans