I normally write API documentation as reStructuredText directly in Python docstrings which are then auto generated via Sphinx. Because I tend to write numerica

I normally write API documentation as reStructuredText directly in Python docstrings which are then auto generated via Sphinx. Because I tend to write numerical algorithms, I also embed math via LaTeX tags. Sphinx converts them to MathJax which renders the math quite nicely. The final output from Sphinx is beautiful (I use the Solar theme [1] for Sphinx). As long as I keep my docstrings up to date, the API documentation generates itself and does so beautifully. I’m sure something similar exists for other languages but I would agree with you that most Doxygen docs are mechanical and devoid of the human touch (most only contain method signatures and non descriptive comments if they exist at all). They are also aesthetically unpleasant which affects their usability, which in turn dampens devs’ motivation to document their code (“why document if the final output is ugly and no one looks at it?”). I wonder if a better theme would help. [1] theme preview here https://vimalkvn.github.io/solar-theme/ https://vimalkvn.github.io/solar-theme/