Move doc to master branch

[tomcombriat]

I might be doing this wrong, but the way I am remaking the docs (and addition to the website), is to have have another folder synced on Mozzi's branch gh-pages.

This implies, for any change in the library, to run doxygen on the main branch, to take into account the new sources, and then copy-paste the result in the gh-pages branch.

I do not have a super clear idea about all this, but wouldn't it be simpler to deploy the website from a folder of the master branch?

[sensorium]

Hi Tom,

it's so long ago I can't remember why I did it that way - maybe to do with testing the website locally while I was learning. If you can streamline the process, go for it.

[sensorium]

I'm sure you've already looked at this... https://docs.github.com/en/pages/getting-started-with-github-pages/creating-a-github-pages-site

I would have just been doing whatever was recommended at the time, I think...

[tomcombriat]

Ok, from what I have read around, the main interest of having the documentation in a separate branch is too avoid cluttering the git history of the main branch and keeping it clean. This is a bit defeated in our case as the doxygen doc, which are always generating huge changes are also in the master branch and edits to the rest of the website are not that common…

---

I am not sure what is the best but I see two different ways of improving the current workflow:

Keeping the gh-page branch

We keep the organization as it is but maybe add a separate github workflow that would take care of generating the docs from the master to gh-page for instance on push. That would quite streamline the process.

Pros:

• less actions required from us
• docs always in sync with the master branch

Cons

• the old docs will remain in the master repo, unless deleted. If we keep them in sync, that defeats a bit the purpose…
• the (updated) docs won't be accessible without an internet access from the master branch which is something I personally find useful.

Moving the website to a folder in master

We move all the website to master (this will need config from the owner of the repo to change the target of the website generation).

Pros:

• no need to checkout between branches to update the doc/website
• doxygen can be triggered manually when an update of the docs if needed

Cons:

• more clutter on the master branch: website and code commits might be hard to distinguish especially with the huge deltas involved.

Any opinions?

[tfry-git]

Another argument for docs in master is that it will be easier to handle code and documentation changes, synchronously, inside a single PR. That would have been nice to have while working on Mozzi 2.0.0.

It may be worth investigating, what would be needed to automate the doxygen-run, entirely, however. I know it's possible in principle to create a github workflow that will generate/deploy the web-pages including both the jekyll and doxygen generation. Doing that would add two significant advantages (if it's not prohibitively difficult to implement):

• The generated doxygen-pages would not need to be in git at all. No cluttered diffs.
• We won't have to remember doing any of this manually.

[tomcombriat]

This last option would indeed be ideal (maybe except for debugging the doxygen doc). I have figured that having a github action running Doxygen seems to be fairly straightforward (https://github.com/mattnotmitt/doxygen-action) but if I am correct, this still clutters diff if I am correct.

Another argument for docs in master is that it will be easier to handle code and documentation changes, synchronously, inside a single PR. That would have been nice to have while working on Mozzi 2.0.0.

Indeed, all the needed changes, to doc, web, can be done in a working branch, alongside the work on the code, I did not think of that but that is a big plus IMO.

[tfry-git]

I believe it will not be necessary for the action to commit the doxygen-generated files to the repository at all. Rather, we'd have to combine everything into an action / sequence of actions that:

1. generates HTML from the jekyll files in a temporary directory
2. generates HTML from doxygen in another temporary directory
3. publishes both on the Mozzi web page.