Add PR documentation preview deployments via GitHub Pages

[Copilot]

Adds per-PR documentation previews deployed to GitHub Pages under previews/pr-<N>/r and previews/pr-<N>/python, with automatic PR comments linking to the previews and cleanup on PR close.

R.yml / python.yml (pkgdown / build-doc jobs)

• Added pull-requests: write permission for PR commenting
• Updated concurrency group to key on PR number (not github.ref) so per-PR deployments don't block each other
• Added Deploy PR preview step targeting previews/pr-${{ github.event.pull_request.number }}/r (or /python); gated to same-repo PRs only via github.event.pull_request.head.repo.full_name == github.repository
• Added Comment PR preview link step using actions/github-script@v7 with a hidden HTML marker (<!-- docs-preview-r-marker --> / <!-- docs-preview-python-marker -->) to upsert a single comment per workflow on reruns

Production deployments (r/ and python/ on push to main) are unchanged.

New: docs-preview-cleanup.yml

Triggered on pull_request: types: [closed]. Checks out gh-pages, removes previews/pr-<N>/ if present, and pushes. Skipped for fork PRs (which never get previews deployed).

- uses: actions/checkout@v6
  with:
    ref: gh-pages
- name: Remove preview folder
  run: |
    PREVIEW_DIR="previews/pr-${{ github.event.pull_request.number }}"
    if [ -d "${PREVIEW_DIR}" ]; then
      git rm -rf "${PREVIEW_DIR}"
      git commit -m "Remove docs preview for PR #${{ github.event.pull_request.number }}"
      git push
    fi

Original prompt

Implement pull-request documentation previews for the repository multi-objective/moocore while keeping the documentation build logic in the existing workflows .github/workflows/R.yml and .github/workflows/python.yml.

Requirements:

• Reuse the existing docs build jobs in R.yml and python.yml; do not introduce a new workflow that duplicates the R or Python docs build steps.
• Add PR preview deployment steps to the existing workflows so that documentation built for pull requests is deployed to GitHub Pages under PR-specific target folders.
• Production deployments must remain unchanged:
  • R docs continue deploying to r/ on push to main
  • Python docs continue deploying to python/ on push to main
• PR previews should deploy to distinct target folders to avoid conflicts:
  • R preview: previews/pr-<PR_NUMBER>/r
  • Python preview: previews/pr-<PR_NUMBER>/python
• Add or update a PR comment in each workflow with the preview URL, but do NOT use marocchino/sticky-pull-request-comment or other non-official comment actions.
• Use actions/github-script instead to create/update a comment via the GitHub API. Prefer a hidden marker strategy so reruns update the same comment instead of creating duplicates.
• It is acceptable to have a separate cleanup workflow, but the docs building must remain in R.yml and python.yml.
• Add a cleanup workflow that removes previews/pr-<PR_NUMBER> from gh-pages when a PR is closed.
• Avoid overwriting the R and Python docs deployments by using different target-folder values.
• Consider fork PR safety/permissions and avoid attempting preview deployment/commenting when the workflow lacks permission to push to gh-pages.

Implementation guidance:

• Update .github/workflows/R.yml:
  • keep existing build steps intact
  • add PR-preview deploy step using JamesIves/github-pages-deploy-action@v4
  • add PR comment/update step using actions/github-script
  • ensure required permissions are present (contents: write, pull-requests: write as needed)
• Update .github/workflows/python.yml similarly.
• Add a new cleanup workflow file, e.g. .github/workflows/docs-preview-cleanup.yml, triggered on PR close, to delete the preview directory from gh-pages.
• Keep changes minimal and focused on preview deployment/commenting/cleanup.

Please create a pull request with these workflow changes.

The following is the prior conversation context from the user's chat exploration (may be truncated):

User: Study how documentation is built and deployed in @multi-objective/moocore/files/.github/workflows/R.yml and @multi-objective/moocore/files/.github/workflows/python.yml I would like to be able to preview the documentation in pull requests. How to deploy to some temporary location and add the link to the pull request?

Assistant: Use GitHub Pages previews per PR, published into a PR-specific subdirectory, and then comment/update the PR with the URL. In your repo, that fits naturally with the existing gh-pages deployments in both workflows.

What you have now:

• R.yml builds/deploys r/docs to gh-pages under r/, but only on push to main.
• python.yml builds/deploys python/doc/_build/html/ to gh-pages under python/, also only on push to main.

For PR previews, the simplest pattern is:

1. On pull_request, build docs.
2. Deploy them to GitHub Pages under a unique folder like:
   • previews/pr-123/r/
   • previews/pr-123/python/
3. Add or update a PR comment with links.
4. Optionally clean up preview folders when the PR closes.

Recommended URL pattern

• Python preview: https://multi-objective.github.io/moocore/previews/pr-<PR_NUMBER>/python/
• R preview: https://multi-objective.github.io/moocore/previews/pr-<PR_NUMBER>/r/

Why this works well:

• no external infrastructure needed
• keeps main docs unchanged
• easy to generate deterministic URLs
• works with your current JamesIves/github-pages-deploy-action@v4

Main caveat

• For PRs from forks, pull_request runs typically do not have permission to push to gh-pages.
• So this will work reliably for branches in the main repo.
• If you want previews for forks too, use pull_request_target very carefully, or switch to another hosting mechanism like artifacts or Cloudflare/Netlify. For security, I recommend starting with same-repo PR previews only.

Suggested implementation

1) R docs preview job

Add another deploy step in .github/workflows/R.yml for PRs.

Conceptually:

• keep existing main deployment to r/
• add PR deployment to previews/pr-${{ github.event.number }}/r

Example:

      - name: Deploy PR preview 🚀
        if: success() && github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository
        uses: JamesIves/github-pages-deploy-action@v4
        with:
        ...

</details>



<!-- START COPILOT CODING AGENT SUFFIX -->

*This pull request was created from Copilot chat.*
>

[github-actions]

📚 Python docs preview for this PR

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 76.98%. Comparing base (6eb5621) to head (d0e0881).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main      #69      +/-   ##
==========================================
+ Coverage   76.95%   76.98%   +0.02%     
==========================================
  Files          67       67              
  Lines        6762     6762              
  Branches     1330     1330              
==========================================
+ Hits         5204     5206       +2     
+ Misses       1210     1208       -2     
  Partials      348      348              

Flag	Coverage Δ
R	71.87% <ø> (+<0.01%)	⬆️
python	74.78% <ø> (-0.13%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

Components	Coverage Δ
C	72.77% <ø> (+0.04%)	⬆️
R	80.92% <ø> (ø)
Python tests	100.00% <ø> (ø)
Python src	82.39% <ø> (ø)

🚀 New features to boost your workflow:

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

[github-actions]

📚 R docs preview for this PR

[MLopez-Ibanez]

@copilot Change this comment to be:

${marker}\n📚 [**Python docs preview** for this PR](${url})\n\n

[Copilot]

Done in d959a86. The comment body now uses the inline link format: 📚 [**Python docs preview** for this PR](${url}).

[MLopez-Ibanez]

@copilot Change the comment for R to follow the inline link format of the Python comment.

[Copilot]

@copilot Change the comment for R to follow the inline link format of the Python comment.

Done in d0e0881. The R comment body now uses the same inline link format: 📚 [**R docs preview** for this PR](${url}).