kimkulling
commented
3 years ago Hi,
thanks a lot for starting this discussion. I really appreciate this. As an introduction: I struggled with our doxygen integration for quit a while. It is hard to maintain the updated doumentation because most people cannot generate it by theirself. You need to install a bundle of tools. So I was asking other developer if they can recommend some better systems. The Godot-Engine recommended ReadTheDocs. So I started some investigations on that.
The input for this documentation is the doxygen file we produced from the 5.0.0-release of Assimp.
The advantages of Readthedocs from my point of view are:
- Installation building in the web as SAAS, - fast feedback-loop for your own PR. Our doxygen-doc wasn't build by the CI because it was pretty hard to get it up and running on travis or githup-actions. People can see their results after minutes life in the web for the current master.
- Easy deployment for updated documentation - comes with its own website to get the latest version, CI and the possibility to build the doc locally by using python + sphinx
- Readthedocs has much more users right now than the doxygen stuff
- Faster in updating the docs even on the current master
- API-Documentation can ge generated automatically, but this is currently work in progress
- Localization support is integrated automatically
Disadvantages from my point of view:
- We need to switch to a new system
- API documentation is currently broken
- Look and feel is not optimized - I need some love here from the community
So that are my reasons to go to Readthedocs. Getting the documentation updated is much easier, but this task is not done right now.
And we have the same situation in the Doxygen-Documentation, but noone hav recognized that.
I saw this project, but it seemed to have a bunch of extra prerequisites and I also wasn't really satisfied with the output. Also it seems weird to have it as a separate project and I'm not sure what the Python is all about.
So I just took the Doxyfile from the source tree, tweaked it a bit, and regenerated the HTML (and CHM and QCH) docs real quick. I put the updated Doxyfile and the built docs at https://github.com/JC3/AssimpDocs. See the READMEs there.
If you want to take the Doxyfile from there, replace the one in the doc folder of assimp's source tree, then drop this assimp-docs project, feel free. You can just require doxygen and build the docs back in the lib's source project. Or just ignore this.
But it's a full, decent looking set of docs if anybody needs it, and there's no extra dependencies or build process beyond running doxygen.
See also https://github.com/assimp/assimp/issues/3789.