vkresch
commented
4 years ago Hey @raphaeldussin @adcroft @marshallward @michaeljones I am currently trying the same for transitioning of the Open Simulation Interface doxygen documentation to Open Simulation Interface Sphinx.
Did you make the full transition or did you encounter some problems? Current problems (cons) which I found are for example:
- no collaboration diagrams with relations between types of fields (maybe needs to be added manually or through some hacking :) )
- HTML Tables (like for this type) in the comments are not supported compare here with sphinx (maybe we can get rid of them or use them in a more sphinxy way)
- currently there is only a alphabetical ordering of messages and you can't really recognize nested messages (this is solveable by creating manually subtopics in sphinx)
(see also this issue).
Can you provide if possible some tips or guides how you transitioned? Do you still keep the doxygen docu for some reason or can it be switched completely to sphinx? Thanks in advance! :)
raphaeldussin
Hi @michaeljones ,
We (@adcroft @marshallward and myself) are considering transitioning our doc workflow from sphinxfortran/sphinxcontrib-autodoc_doxygen to breathe. An example of what we are currently able to get from the Doxygen documentation into rtd is:
https://mom6.readthedocs.io/en/dev-gfdl/api/generated/modules/mom_meke.html
Doxygen reference:
https://noaa-gfdl.github.io/MOM6/APIs/namespacemom__meke.html#details
Is it possible to reproduce what we've got using breathe? If so, do you have any pointers to where we should start? We've played a little with it but didn't got more than list of functions with parameters.
Thanks!