GitHub Actions: test and doc

[umarcor]

Fixes #142

A GitHub Actions workflow named 'doc' is added for building the docs.

• The output is uploaded as an artifact of the workflow run, as well as pushed to branch gh-pages.
• Users can download the artifact of any run for having an offline version of the docs (Add instructions on how do download for offline usage #142).
• Any contributor that forks the repo (and pushes changes) will have the content automatically uploaded to username.github.io/fomu-workshop.

[mithro]

@umarcor - Could you rebase this change onto master?

[umarcor]

@mithro, done.

Note: the first time GitHub Actions creates gh-pages, the content is not automatically published. An owner (not a contributor) of this repo needs to push to gh-pages once, for GitHub Pages to be triggered. From there on, updates committed by GitHub Actions will be automatically picked. For that first push, do the following:

git fetch --all
git checkout -b gh-pages origin/gh-pages
git commit --amend --reset-author
git push origin +gh-pages

[mithro]

@umarcor -- There isn't an upstream gh-pages branch at the moment?

[umarcor]

@mithro, you are correct. I configured it for running the workflow on push or pull_request, but gh-pages is NOT updated by pull_requests: https://github.com/im-tomu/fomu-workshop/pull/317/files#diff-2bf3c905e9c6203095ea31e889d43bfbR31. Hence, the branch will be created after this PR is merged.

Regarding the failing macOS test, it seems that #316 had not reached the rate limit yet, but it did now. I will investigate how to retrieve the required metadata while minimizing the number of API calls. GitHub API v4 allows quite complex request to be done at once.

[mithro]

@umarcor - Is there a way to get the uploaded docs to appear in the "This branch has not been deployed" section of the GitHub UI?

[umarcor]

@mithro, not exactly. However, if you wait until work "doc / sphinx (pull_request)" is green, clicking on "Details" will take you to the page where the artifact is displayed. See top-right corner of the "log box": https://github.com/im-tomu/fomu-workshop/pull/317/checks?check_run_id=1212784095. Artifacts are also shown one level above: https://github.com/im-tomu/fomu-workshop/actions/runs/290651865. Is this what you meant?

[mithro]

I have always been very confused at how the get-toolchain.py script could be hiting an API limit given it should be doing like 4 web page requests?

[umarcor]

@mithro, on the one hand, I opened #327. On the other hand, I think it might be related to how each file is retrieved and/or checked. That's what I'm checking.

BTW, why is get-toolchain.py still compatible with Python 2?

[mithro]

Because we want it to be as compatible with as many old systems as possible.

[umarcor]

@mithro, now gh-pages was created (https://github.com/im-tomu/fomu-workshop/tree/gh-pages), but https://im-tomu.github.io/fomu-workshop is still empty and https://github.com/im-tomu/fomu-workshop/deployments does not exist. Can you please execute the set of commands in #317 (comment) ?

Once you do it, the deployments page will change to something similar to https://github.com/ghdl/ghdl-cosim/deployments

EDIT

A better example, my fork:

• https://github.com/umarcor/fomu-workshop
• https://github.com/umarcor/fomu-workshop/tree/gh-pages
• https://github.com/umarcor/fomu-workshop/deployments/

[mithro]

@umarcor -- Does it appear to be working now?

[umarcor]

@mithro, I would say that one of dependabot's branches was automatically updated. That updated gh-pages with dependabot's user, which made the content be served: https://im-tomu.github.io/fomu-workshop/. Hence, the "nightly" build of the docs is being served. That's working.

However, the deployments page does not exist yet: https://github.com/im-tomu/fomu-workshop/deployments. That's because no owner commited to gh-pages yet. You need to do whatever change to that branch and push once.

[umarcor]

Note that we can prevent branches other than master updating gh-pages, as dependabot did. Let me know if you want to do so, and I'll update the condition in the workflow.

[mithro]

@umarcor - That seems sensible, please do so!