Move documentation from Read the Docs to GitHub Pages?

[jnikula]

I set up a github workflow to build and deploy documentation in github pages: https://github.com/jnikula/hawkmoth/blob/master/.github/workflows/docs.yml. The documentation is deployed at https://jnikula.github.io/hawkmoth/.

The main benefit would be more control over the environment in which Hawkmoth is run to produce the documentation. There are no guarantees Clang is available in the Read the Docs environment, so we've got a bunch of hacks to mock the results from test cases if using Hawkmoth on RTD does not work. We could throw all that away and simplify with a move to GitHub Pages.

RTD does have support for multiple documentation versions out of the box as well as PDF builds.

@BrunoMSantos thoughts?

[BrunoMSantos]

Yeah, sounds like a good idea to me, I've never really liked RTD for many of the same reasons. And you already looked into it, so it's (nearly?) there already.

I'd argue that we should limit documentation updates to new tags. I'm not really familiar with GitHub's CI, but it seems like you're doing it for anything that is not a pull request. Does that include any new commit or even any new branch?

As for having multiple versions, the landing page should still be that of the latest tag, so we'd need some sort of hack to link to other versions from within it I guess. Not sure how we would manage that, but it could be a separate issue for later.

[BrunoMSantos]

By the way, this reminds me of #25 and the bits of documentation added for it.

On the one hand, that might still be valid and helpful advice for those who care, on the other hand, it was already a liability when we weren't using that specific method ourselves and it's even less justifiable if we are no longer using RTD at all. I wouldn't mind cleaning that up too as it's bound to rot if it hasn't already, but I'd leave the decision to you since you know the subject better.

[jnikula]

Sorry for the delay in response. Good insights. RTD handles the versions nicely, so maybe I need to figure that out before switching to GitHub pages completely.

The hawkmoth.util.readthedocs thing is maybe a dozen lines of code, so not a big deal, really.

[jnikula]

I've added both stable and development documentation to github pages, with deployment using github workflows. It works nicely.

Additionally RTD has introduced a configuration file that lets you specify the environment better as well as install dependencies using apt. So I figured I'd keep both. And also documented the RTD part better: https://hawkmoth.readthedocs.io/en/latest/installation.html#read-the-docs