use doxygen

[alexjbest]

• turn of latex and html generation in doxygen if we dont want them
• see if we want any dot graphs or anything in the sphinx output
• look more into the macro expansion options
• enable building of man pages in flint (@pascalmolin wants these)
• compare with standardese
• look into https://github.com/sympy/sphinx-math-dollar
• decide on style of comments

[fredrik-johansson]

Can the blank line in

/**

    Initializes *cache* for use.
*/

be omitted? Can one even do

/** Initializes *cache* for use. */

?

[alexjbest]

Yes you can, the current situation is just an artifact of me being lazy when copy-pasting

[albinahlback]

I would really be in favor of switching to Doxygen

[edgarcosta]

Can someone point me to some the advantages of doxygen? (I am just curious, I am sure @alexjbest told me a about them, but I have forgotten)

[albinahlback]

Can someone point me to some the advantages of doxygen? (I am just curious, I am sure @alexjbest told me a about them, but I have forgotten)

I have just looked at their website (https://doxygen.nl/index.html), and for me it would be that it:

1. Natively handles Markdown
2. Can produce very nice but simple and efficient HTML sites (see KDE's documentation for instance),
3. Natively support C(++)

I think (1) and (3) are quite important for me. I haven't been able to find the efficiency of Doxygen yet, but I assume it is not too bad.