Add doxygen docs to Github Pages

[yohannd1]

This PR adds a github workflow that runs doxygen on the codebase and uploads the generated HTML pages to Github Pages. My aim with this is to make reading the docs easier and browsing through the documentation simpler.

This workflow was based off the build workflow already present in the repo, plus some prior Github Pages experiments I've worked on.

Things to consider:

• Where will this be hosted? I think in the current state it would go to https://lmms.github.io/lmms.
• Would this run on every branch? Might need to restrict it to the main branch or find a way to have docs for multiple branches/PRs at the same time.

[yohannd1]

Note that the CI run inside the PR does not work fully, as it is denied acess to github pages. Not sure if there's a way to work around that. In fact, I'll be disabling this run on PRs for now.

[messmerd]

Following the advice from this Stack Overflow article, I just set the GitHub Pages source for this repo to GitHub Actions.

Try again and see if it works now.

[yohannd1]

That seems to not have worked - it did go farther, but it still has permission-related errors:

I will now be trying rossjrw/pr-preview-action, which might be able to solve this.

[messmerd]

I will now be trying rossjrw/pr-preview-action, which might be able to solve this.

I don't think that will work, unless we set things up differently here.

From that action's readme:

[yohannd1]

Ah, I see. From what I've read here it seems it is possible to adapt the workflow here, but I'm not sure if it would be worth it - pushing tons of generated HTML and graph files of tons of PRs is probably going to bloat the repo a lot.

[JohannesLorenz]

What I checked:

• Code
• Style

[JohannesLorenz]

All the dependencies and make options should not be relevant to Doxygen? (except the doxygen dependency)

[yohannd1]

I believe the make options indeed are not relevant, I'll be removing these.
As for the other dependencies, I'm not sure. I think some are needed so Doxygen can figure things out, or at least to list them (this depends on the other discussion).
In any case, the wine dependency is probably not needed?

[JohannesLorenz]

Very likely not.

Can you run once with and once without dependencies, and compare the results which doxygen produces?

[yohannd1]

Ran it without most dependencies, and it seems the output hasn't changed. The class list, at least, seems identical. My concern was that plugins such as ZynAddSubFx wouldn't be included there but that hasn't happened.
Note that I'm still including the Ubuntu 20.04 dependency set, as it includes dependencies on Qt and other libraries, but I'll briefly try removing most of these as well.

[yohannd1]

but I'll briefly try removing most of these as well.

Okay, that didn't work.

[JohannesLorenz]

Looks like we need to provide the minimum dependencies to let CMake pass, and that's all we need...

[yohannd1]

Managed to remove a few more dependencies. I still don't know about removing libraries used by the code though, so I'm leaving these for now.

[JohannesLorenz]

A lot of classes/types by Doxygen (almost all) are not by us (Lv2, Sord, Asio, Calf, ...).

As you said in Discord, you would like to keep it. I leave the comment here for discussion.

[JohannesLorenz]

doc/CMakeLists.txt queries DOXYGEN_FOUND, but my system never sets this variable:

$ grep -i Doxygen CMakeCache.txt 
//Dot tool for use with Doxygen
DOXYGEN_DOT_EXECUTABLE:FILEPATH=DOXYGEN_DOT_EXECUTABLE-NOTFOUND
//Doxygen documentation generation tool (https://www.doxygen.nl)
DOXYGEN_EXECUTABLE:FILEPATH=/usr/bin/doxygen
//ADVANCED property for variable: DOXYGEN_DOT_EXECUTABLE
DOXYGEN_DOT_EXECUTABLE-ADVANCED:INTERNAL=1
//ADVANCED property for variable: DOXYGEN_EXECUTABLE
DOXYGEN_EXECUTABLE-ADVANCED:INTERNAL=1

The documentation says you should query Doxygen_FOUND, so I think we should query both.

Still, that does not work on my system. Might be out of scope for this PR though.

[yohannd1]

Testing this right now with this commit. I do think it is close enough to what this PR is touching, so I think it's worth it to try it here.

[yohannd1]

It does error out, but it seems it is erroring even when the docs are not being built. I think it is being run even when the doc target is not among the specified.

[yohannd1]

Managed to fix it on 069f3ab, through a dummy target that runs an echo and false. I'm just not sure if it works cleanly on pure windows, because afaik false isn't a command there. It should still error out, I guess, but the error will be more confusing.