ci: Build docs failure on PR

[fraya]

The GH Action build-docs fails when trying to deploy to GH Pages in a PR. This happens because the runner does not have write permissions to the branch in a PR.

Proposed Solution:

Split the action into two separate workflows:

1. docs-build-and-check-links.yml (runs on PRs)

   • Executes make linkcheck to detect dead links.
   • Executes make html to check for documentation build issues.

2. docs-build-and-deploy.yml (runs on push)

   • Runs the same checks as above.
   • Deploys the documentation to GitHub Pages on push.

[cgay]

I just noticed this bug. I just merged #203 , which was probably more drastic than necessary, but was a quick fix to prevent the failures.