Automatic deployment of doxygen/gh-page on push on Master

[tomcombriat]

This might be an answer to #289 .

Sorry for the enormous diff change, moving the whole site is quite some thing, but I actually thing some of it can be removed (I can safely remove the doc/html folder right?).

In a nutshell: this adds a workflow to automatically compile the doxygen sources, the website, and publishes it. All the sources are on the master branch.

I have tested on my own fork first and changes both on the doxygen comments and on the website are correctly deployed.

For this to work, in the Settings/pages the source of deployment should be set to GitHub Actions.

I'll try to do a bit of cleanup also.

[tomcombriat]

Ok, that seems to work, more or less, but I still have a problem with styling, as you can here.

I think that it does take into account the doxygen.css file, and generate its own depending on the version of doxygen used. Might be worth putting the custom options in custom_stylesheet.css or did I miss something?

I think overall, this might be easier to maintain: all is in the same branch, and generated on push on master, which allows to fix things before a release. All the html files are not in the repo anymore… What do you think?

[tomcombriat]

Updated, the custom style sheet doxygen.css is now taken into account, but does not look good IMO, reverted to black (default on the machine this is compiled on by gh-action).

There might be a bit of possible cleanup, but my brain is a bit fried now fighting with actions…

[tfry-git]

Wow, this is great!

As for the CSS, I suggest not to worry too much, at least for the time being. The difference between API and "main" styling may be more prominent with the new defaults, but it's not like we had consistent style, before. One thing we may want to look into is a back link from the API section to the main website (but that's not a regression, either).

Would the arduino-lint action be happy, if the gh-pages folder was moved to extras/doc? Or would it even be possible to drop the .ino files from within gh-pages, and copy them straight from the examples folder, as part of the workflow?

[tomcombriat]

Thanks! It was a bit of a traumatizing fight but I think it is a satisfying solution. The fact that the html will not be part of the repo is a good thing on the long run (except for this merge…). I learnt quite a bit in the process!

Yes, arduino-lint did not like that, I have to admit that I initially did not care with it but looking a bit in details it indeed seems that the .ino files in the docs are confusing it.
I think, in order to help to keep things in sync, duplications should be avoided and sketches should only be in the source. Might be worth, but probably a bit of troubles, to copy them by an action in the pages. But where to keep the audio files in that case (I actually forgot to transfer them also…)? Might be worth having them in the example/folder actually? The full markdown for the example page could actually be generated by an action. Might be a bit of troubles, I will try to think about it once I get a bit of time. If you have some ideas also.

Otherwise, we can just put the pages in something arduino-lint does not probe (extras), that's probably easier ;). I also do not have strong feeling about that folder name. gh-pages might be more confusing than anything as it is also the name of a branch.

Opinions?

[tfry-git]

Yes, we won't have to do everything at once. We can still look into further automation (the .ino files, etc.) later. I suppose a folder below extras should keep arduino-lint happy. Perhaps call it extras/website. Not sure whether it makes sense to have the audios in the examples folder, or what arduino-lint would think about that. They are not "source" files in any way, after all. But either way, once we have everything in a single branch, it should be trivial to move files around, as needed.

[tomcombriat]

arduino-lint seems to be happy now! Reports not really but that's been a common issue for PR from a fork…

I will do a bit of cleanup, both in the files and in the commits and will mark it as ready.

[tomcombriat]

Alright, I think this is looking good! You can check the deployment https://tomcombriat.github.io/Mozzi/ and the status of the actions on https://github.com/tomcombriat/Mozzi/

To not forget before merging (need to be at last minute):

• adapt extras/website/_config.yml to point to the real website
• change the way the site is deployed from the settings of Mozzi (only @sensorium can do it I think)

On the longer run:

• maybe remove the gh-page branch to lighten a bit the repo?
• automatic examples page creation?

Edit:

I had to fight a bit to get the "Modules" section of the documentation to show… The way I found around it is to use a previous Doxygen version… As a side effect, the theme returned to the previous one :)

[sensorium]

Hi Tom,

change the way the site is deployed from the settings of Mozzi (only @sensorium can do it I think)

Let me know what I need to do when you're ready.

[tomcombriat]

Hi @sensorium !

So, the steps are as follow: on github and on Mozzi repo: Settings > Pages > Build and development > Choose "GitHub Actions" instead of "Deploy from a branch".

Normally that should not break the website until something is pushed to main, but just to be sure I prefer to be around once you do that so maybe we can plan the transition for say, this weekend? (I'm on UTC+1).

This also let a bit of time if @tfry-git wants to change something or hang it in order to have a closer look!

[sensorium]

maybe we can plan the transition for say, this weekend? (I'm on UTC+1)

so at 9pm here (utc+11), would it be 11am there? Will we try Saturday?

[tomcombriat]

so at 9pm here (utc+11), would it be 11am there? Will we try Saturday?

Yup! If that is okay for you! I think it should go smooth ;)

[sensorium]

Hi @tomcombriat , I just made the change. What happens next?

[tomcombriat]

Hi @sensorium , I'll wait for these tests to finish and merge! (And hope that it behaves as expected ;) )

[tomcombriat]

Looks good! https://github.com/sensorium/Mozzi/actions/runs/12328971614

[sensorium]

┈┈┈┈┈┈▕▔╲
┈┈┈┈┈┈┈▏▕
┈┈┈┈┈┈┈▏▕▂▂▂
▂▂▂▂▂▂╱┈▕▂▂▂▏
▉▉▉▉▉┈┈┈▕▂▂▂▏
▉▉▉▉▉┈┈┈▕▂▂▂▏
▔▔▔▔▔▔╲▂▕▂▂▂