Deploy documentation automatically from `main`

[tlestang]

This add a GitHub workflow to build the documentation website from sources in docs/. The built website is pushed to the gh-pages branch which can be used by GitHub to deploy the site.

In practice the documentation will be built and deployed each time commits are added to the mainbranch.

Somebody with elevated privileges (I think one of @andreww @c-martinez @tonymugen or @Llannelongue )should go into the repo settings and enable GitHub Pages to be deployed from the root of the gh-pages branch. It's also important to check that Actions have read/write permissions (from the Actions section in the settings page).

[tlestang]

Thanks for taking the time to try it out @sadielbartholomew . I'm suprised this is not working out, since I also performed a similar test on my fork:

https://tlestang.github.io/cats/

You should'nt need to create a gh-pages branch yourself, as it's created by ghp-import automatically in the deployment workflow.

If you pushed this PR branch directly to your fork (as sadiebartholomew/docs_gh_actions), you'll need to change the trigger branch to be docs_gh_actions instead of main. Or you can push these changes (2539adb) directly to your fork's main.

[sadielbartholomew]

Hi Thibault. Sorry for the late reply, mostly due to my being on annual leave last week.

Thanks for the clarifications. I'll have another look today and see if I can get it to work in the way you suggest. I did wonder if manually creating a gh-pages was necessary, though I resorted to it to explore what happened since I didn't see any branches being generated.

[ljcolling]

this looks like there's still an issue with deploying, no?

I looks like it's just the permissions... it's should work now when this is merged into main..

Once the gh-pages branch is created by this action, then I'll make sure that everything is set up in the setting correctly.

[tlestang]

hmm I guess somebody with elevated privileges in this repo will still need to grant actions write permissions? Otherwise anybody could commit a workflow with write access? Let's see!

[tlestang]

It did work :thinking: I also notice that I have access to the repo's settings now. I thought I didn't before.. Anyway - that's up and running now. Thanks @ljcolling !

[ljcolling]

Yeah, it was just

    permissions:
      contents: write

which I think is a new thing, because a bunch of my other auto gh-pages deploys also recently broke and needed that to fix it

[sadielbartholomew]

Brilliant stuff, thanks both! Great to see the built documentation over at greenscheduler.github.io/cats/.

That said, whilst it all otherwise looks like it should, the API reference hasn't been auto-populated as should be achieved through the Sphinx HTML build. Any ideas why that is (the logs might reveal these but I don't have much time right now to check)? I'll open a separate follow-on issue to note that this should be fixed...