Devops: publish documentation using first-party actions

[daidahao]

Checklist before merging this PR:

• Mentioned all issues that this PR fixes or addresses.
• Summarized the updates of this PR under Summary.
• Added an entry under Unreleased in the Changelog.

Fixes #.

Summary

This PR proposes using GitHub Actions to publish the documentation to GitHub Pages, replacing the previous third-party branch-based deployment method.

I am a bit wary of using third-party action s0/git-publish-subdir-action@v2.2.0 for publishing the documentation. The action has not been updated in a long time (last release was 2022), is owned by an individual, and has access to secrets.GITHUB_TOKEN which could write to any branch.

Meanwhile, the GitHub Pages documentation recommends using actions/upload-pages-artifact and actions/deploy-pages, both first-party actions, to publish the site. This PR adopts the flow for better security and long-term support.

As suggested in actions/deploy-pages, I've also:

• split deploy-docs into build-docs and deploy-docs to prevent code execution
• restricted GITHUB_TOKEN permissions for deploy-docs job to only those necessary.

@dennisbader If you agree with this, you would need to change Pages settings for the next release to use "GitHub Actions" as source to replace "Deploy from a branch".

Other Information

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 96.24%. Comparing base (6e1fdf2) to head (858c748).

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #3107      +/-   ##
==========================================
- Coverage   96.31%   96.24%   -0.07%     
==========================================
  Files         161      161              
  Lines       17356    17356              
==========================================
- Hits        16716    16705      -11     
- Misses        640      651      +11     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[jakubchlapek]

Hi @daidahao, thanks for the PR!
After looking into it, I definitely second the change to leverage first-party actions instead. The current solution is quite dated (you mentioned 2022, but the pinned version we use comes from even 2020) and not maintained. The schemas look consistent with the documentation. One additional element we can add is limiting the build-docs job to contents: read access, as it doesn't require write I don't believe since we write the documentation as artifacts, and not touch the repo. Besides that it looks good to me, good catch :)

[daidahao]

@jakubchlapek

Thank you for taking a close look at this and I am glad that you agree with the proposal.

Regarding the contents: read access, my understanding is that the permission field of each job applies to GITHUB_TOKEN only. Because we are not using GITHUB_TOKEN in build-docs, so we do not have to declare permission for the job either.

Another outdated job I have looked at is actions/create-release@latest (last update in 2020 and using Node.js 20). Unfortunately, I could not find an official alternative to this action. Would love to know what's your opinion on this.

[dennisbader]

Looks great, thanks a lot @daidahao 🚀
Will merge once all tests have passed

[dennisbader]

@daidahao, I also updated the GitHub Pages settings, so this one should be good to go 💯