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).

[sadielbartholomew]

Hi Thibault. Thanks for addressing this.

Logically, by eyeballing it, the workflow all looks sound.

To review what the workflow generates I pushed this branch to my own fork and played about with the Pages and Actions settings there, in line with what you advise in the opening comment here that we need to do for the upstream 'GreenScheduler' repo.

Now, I'm not sure if it's me not setting the GitHub Pages and Actions settings correctly or not, so I'll outline precisely what I set below in case you can spot something I did wrong, but I'm seeing only our standalone 'README' page rendered apparently via Jekyll rather than the Sphinx site, so either I'm setting it up wrong on the repo settings side, or it is the case that the README page will be generated and deployed from this workflow here on the upstream, which is obviously not what we want (or there's a subtle difference in what will happen on the upstream repo and on my fork).

So overall I'm not convinced this is doing quite what it should, namely that it should show the Sphinx on the deployed site rather than the just the README page for the repo. What do you think - have I configured my review test wrong or does it indeed seem like the workflow needs updating somehow to deploy and show the Sphinx built site?

---

Details: recap of steps and results of test on my fork

Steps

(0. First I pushed this branch to my own fork of cats, to use there.)

Then, I did both steps you mentioned for my fork, as shown (screenshots in case you might be able to spot something not configured right), namely:

1. I did this:

go into the repo settings and enable GitHub Pages to be deployed from the root of the gh-pages branch.

2. The I set this:

It's also important to check that Actions have read/write permissions (from the Actions section in the settings page).

3. I created a copy of main called gh-pages since without that I was seeing a 404 error on the link the deployment said was the site, namely: https://sadielbartholomew.github.io/cats/,.

Results

The deployment CI job runs on Actions and links to the rendered site: see the latest job on https://github.com/sadielbartholomew/cats/actions. This showed a deployment location/URL at https://sadielbartholomew.github.io/cats/, which only shows the README (follow the link to see that, I won't touch it so it will still be there).

So that's not what we are hoping for.

[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.

[ljcolling]

I think this can be merged now if you'd like @tlestang

[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 🤔 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...