Added modern style Doxygen Awesome documentation

[githubuser0xFFFF]

The following pull request is meant as a proposal to add modern, responsive and mobile friendly style to Quarter library documentation that supports dark and light style. The doxygen style is based on the Doxygen Awesome project.

While the Coin3D libraries are up to date and usable with the latest Qt6 version, the documentation looks really old and outdated - like from the 90s. This gives the impression of an old and outdated project. Especially browsing the documentation on mobile devices is a pain.

If the pull request will be accepted after a discussion and some changes, I'm ready to update also the other coin libraries.

To avoid breaking the current documentation or the creation of CHM and QCH help files, I added a completely new build target documentation_awesome.

[VolkerEnderlein]

The brief description has to be quoted, otherwise all whitespace is lost.

[VolkerEnderlein]

The tag file has to be created in the html_awesome directory, otherwise building both doc styles fails when running CMake.

[VolkerEnderlein]

I really like the awesome style. Thanks for the amazing work you did on the documentation. It is highly appreciated.

[githubuser0xFFFF]

Hi Volker,

I have a few more questions about your opinion on the integration of the new style:

• the GitHub logo in the right corner of the header of the new documentation, should it link to https://github.com/coin3d or to the specific library (in this case https://github.com/coin3d/quarter)
• there are several ways to install the doxygen awesome files in the project (https://jothepro.github.io/doxygen-awesome-css/index.html#autotoc_md11). For the first review I manually copied the files into the project. Another option would be the integration via a Git submodule. If we link the GitHub logo to https://github.com/coin3d then we could use a common HTML header for all libraries. If you prefer to link to a specific library such as https://github.com/coin3d/quarter, then we need to provide a html.header.in file for CMake, to fill in the right link

So what is your opinion?

Kind regards, Uwe

[VolkerEnderlein]

Thanks Uwe, I would prefer linking to the specific library repo as the coin3d repo contains too many subrepos. Quarter is pinned but other repos are not. If we'd link the subrepo one could easily jump right to the source code of interest. As for the question whether to link the doxygen_awesome repo as submodule i tend to fork it and use the fork as submodule. That way the dependency is never broken and can be updated as needed. What do you think about this? Cheers, Volker

[githubuser0xFFFF]

Hi Volker,

I completely agree with your proposal - this was also my idea and it is a clean solution.

I updated the branch, to include doxygen-awesome as submodule and added a header.html.cmake.in where the GitHub link is inserted from the CMakeLists.txt file just to prove, that it works. So that means we can use a common header.html.cmake.in file for all coin3d repositories and fill in the required repo link via CMake configuration step.

I also added some code to CMakeLists.txt to update the submodules during configuration to ensure that the documentation submodule is properly initialized.

So it would be great, if you could fork the doxygen-awesome project to prepare the next steps. The next question is, where we add the header.html.cmake.in file. Because it is common to all coin3d repos, I would like to see it in the git submodule. There are two options for this:

• option 1: we create coin3d specific doc repo and add the header.html.cmake.in there and then add the doxygen awesome project as a submodule to this doc repo. Then we include the doc repo as submodule into the coin3d repo - this is quite similar to the current state
• option 2: we create our own coin3d branch in the forked doxygen awesome project and add all modifications there

I would prefer option 2 because I do not really like ther complexity of a git submodule in a git submodule. But this is only a personal feeling so feel free to do it the way you like. So I would say:

• fork the doxygen-awesome project
• create a custom coin3d specific branch from the latest release tag
• add header.html.cmake.in to the doxygen-custom subfolder

[VolkerEnderlein]

Hi Uwe, thanks for your fantastic work on this PR. I just created the doxygen_awesome_css fork in the coin3d repository. You can adjust the submodule to it. The other questions/steps will be done this evening. Cheers, Volker

[githubuser0xFFFF]

Hi Volker, thank you for this quick response - great. I'm waiting until you have done the other steps this evening so that I can pick the right branch (coin3d) for the submodule.

Thank you.

[VolkerEnderlein]

Thanks Uwe,
I just had an extensive look onto the structure.
In addition to option 1 and 2 I see another option 3 that uses a specific header.html.cmake.in in the docs folder for every subrepo of coin3d. As we already have an repo specific doxygen file this would put not a large burden on the project (although the file would be the same for all repos in the initial state). That way we can use the main branch of our doxygen-awesome-css fork without modifications or project specific branches. A simple recursive checkout of e.g. quarter repo would get you the right version of the submodule without any actions in the CMakeLists.txt.
And it would keep us the option open to later add repo specific content to the html page.
What do you think about this?
Cheers, Volker

[githubuser0xFFFF]

Hi Volker,

If we include the doxygen-awesome style as a submodule, then we need to checkout a specific release branch (i.e. the latest release) - that means, we do not use master / main. If we have to check out a branch anyway, then it makes no difference whether it is a release branch or our coin3d branch. If we need to switch to another doygen-awesome release, because of new features or fixes, then we need to update all repositories that include the submodule to checkout the right branch / tag. If we us our coin3d branch, then we always know, that we have a working branch and we never need to update the other repos anymore.

If we switch to a new doxygen-awesome release, then we only need to update our coin3d branch to the specific release. So I'm more for a coin3d branch in the submodule.

And if we have our own branch, then it is easy to place a global working header.html.cmake.in into the doxygen-custom folder. That means any coin3d repo can use this file as is, or if it needs to do repo specific changes, then it can add a custom header.html.cmake.in file in the docs folder of the specific repo. So I would keep as many as possible of the documentation stuff global and out of the coin3d repos but give the repos tjhe option to provide its own file if required. I think for the quick start, a global file is o.k.

[VolkerEnderlein]

Hi Uwe,
I am now convinced the solution you proposed is best :). I added a coin3d branch to the doxygen-awesome-css fork and also added the html.header.cmake.in file to this branch in the doxygen-custom folder. Cheers, Volker

[githubuser0xFFFF]

Hi Volker,

Thank you for providing the doxygen-awesome fork with the coin3d branch. I updated this pull request to use this fork and I also did the following changes:

• updated quarter.doxygen.awesome.cmake.in to latest doxygen 1.10.0 to get rid of warnings
• I activated sorting of member functions - this is also done by Qt library (https://doc.qt.io/qt-6/qobject.html) and I think it helps to find functions

So I would say, this pull request is ready now from my point of view.

[VolkerEnderlein]

Thanks Uwe, do you think we really need the default doxygen comments in the quarter.doxygen.awesome.cmake.in file? I removed them some time ago, because they changed alot between versions and prevented me from easy diffing the .in files between subprojects. If you specify -s on the doxygen commandline when updating the configuration files the comments are omitted. Cheers, Volker

[githubuser0xFFFF]

Sorry - I searched for this switch but could not find it - I just updated the file with a stripped version.

[VolkerEnderlein]

Thanks for this valuable contribution to Coin3d development. Keep up the good work.