Here is the example of documentation from my library. Includes: examples (evaluated during doc generation), images (pregenerated or generated from code snippets), categorization, constants extraction, math formulas. Based on metadata, codox and markdown. Solution is quick and dirty (treat it as poc) and based on docstrings manipulation. I think having such metadata in the code could be easily used directly by doc tools (codox) or editors (emacs/cider) via proper interpretation.

https://clojure2d.github.io/clojure2d/docs/codox/clojure2d.math.html

or https://clojure2d.github.io/clojure2d/docs/codox/clojure2d.core.html#var-point