feat: Add PR documentation previews via gh-pages subdirectory deployment

[Copilot]

The docs workflow only deployed on pushes to main. PRs had no way to preview documentation changes before merging.

Changes

.github/workflows/docs.yml

• Added pull-requests: write permission (required for bot comments)
• Deploy PR Preview: on pull_request events, deploys built docs to gh-pages under pr-<number>/ using peaceiris/actions-gh-pages@v3 with keep_files: true to avoid clobbering main docs
• Comment PR Preview URL: posts (or updates) a single bot comment on the PR with the live preview link — https://griffithslab.github.io/whobpyt/pr-<number>/

.github/workflows/docs-pr-cleanup.yml (new)

• Triggers on pull_request: types: [closed] for main/dev
• Checks out gh-pages, removes pr-<number>/, and pushes the deletion to keep the branch clean after PRs are merged or closed

Original prompt

Enhance the existing GitHub Actions workflow for documentation at .github/workflows/docs.yml to provide documentation previews for pull requests.

Requirements:

• On pull_request events (to main or dev), build the docs and deploy them to the gh-pages branch under a unique subdirectory named by the PR number (e.g., pr-<PR_NUMBER>/) so that each PR has its own preview site (e.g., https://griffithslab.github.io/whobpyt/pr-123/).
• Keep the current behavior for main branch pushes (deploying built docs at the root of gh-pages).
• Document or script the PR-number subfolder logic. Make sure only PRs from the main repo (not forks) attempt deployment to avoid leaks.
• (Optional but preferred) Add an action step that comments on the PR with the preview URL upon deployment.
• Ensure the workflow remains compatible with the current Sphinx/Makefile build pipeline.

Do not disrupt main docs publishing; only add or modify to enable isolated PR previews.

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

User: there is currently an empty docs page saying 'installation and usage'. put it there

https://griffithslab.github.io/whobpyt/documentation/usage/index.html

Assistant: I am submitting a pull request to add clear installation instructions to the "installation and usage" documentation page in GriffithsLab/whobpyt. The instructions will include pip-based installation, optional steps for installing from source, and usage verification. Once the PR is open, I will share the link for your review.

User: @copilot Accepted Confirmation: Are you sure?

Assistant: ````list type="task"
data:
- title: '[WIP] Add installation instructions to documentation page'
repository: GriffithsLab/whobpyt
url: https://github.com/copilot/tasks/pull/PR_kwDOHY95Vc7LAbfm
state: queued

The Copilot coding agent has started working on your request to add installation instructions. You can track progress and review the pull request at the link above.

User: add contributor guidelines. this is the page

https://griffithslab.github.io/whobpyt/documentation/development/index.html

base it off MNE and nilearn

Assistant: ````list type="task"
data:
    - title: '[WIP] Add contributor guidelines to development documentation, inspired by MNE and Nilearn'
      repository: GriffithsLab/whobpyt
      url: https://github.com/copilot/tasks/pull/PR_kwDOHY95Vc7LAbgQ
      state: queued

The Copilot coding agent is now working on adding contributor guidelines to your development documentation, following patterns from MNE-Python and Nilearn. Track progress and review the pull request using the link above.

User: @copilot Accepted Confirmation: Are you sure?

Assistant: ````list type="task"
data:
- title: '[WIP] Add contributor guidelines to documentation page'
repository: GriffithsLab/whobpyt
url: https://github.com/copilot/tasks/pull/PR_kwDOHY95Vc7LAfvk
state: queued

The Copilot coding agent has started working on your request to add contributor guidelines (modeled on MNE and Nilearn) to your development documentation. Track progress and review the pull request at the link above.

User: how can I view the website that is built by the CI when a PR is submitted ?

Assistant: Great question! This is commonly known as a "preview deploy" or "docs preview" for pull requests. The process and the link depend on how your documentation build and deployment is set up in your CI (e.g., GitHub Actions or Read the Docs). Here’s how it typically works and what to look for:

---

## 1. **GitHub Pages PR Previews (with GitHub Actions)**
If your repo uses GitHub Actions and the build workflow is set up to deploy PR previews (using tools like [peaceiris/actions-gh-pages](https://github.com/peaceiris/actions-gh-pages) or [pypa/cibuildwheel](https://github.com/pypa/cibuildwheel)), here’s what happens:

- **Check the PR Checks/Statuses:**  
  When you open a PR, CI jobs will appear at the bottom of your PR under “Checks.”
- **Look for a “Deploy Preview” or “Docs preview” job:**  
  If a preview is built, the job often posts a link as a comment, or the check details link leads to a unique web URL for your PR docs preview (e.g., `griffithslab.github.io/whobpyt/pr-123/`).
- **No Preview?**  
  If there's no such job, your CI is likely set up only for main-branch deploys.

## 2. **Read the Docs PR Previews**
If you use [Read the Docs](https://readthedocs.org/):

- On each PR, Read the Docs will add a status (“docs/readthedocs.org: whobpyt PR-123”) with a link to the preview at  
  ```
  https://whobpyt--<PR_NUMBER>.org.readthedocs.build/en/<PR_NUMBER>/
  ```
- The bot often posts a comment with the direct link.

## 3. **Setting Up PR Previews (If Not Already Enabled)**
If your repo does **not** yet offer PR previews for the docs site:

- **GitHub Pages Preview:**  
  You’ll need to enhance your Actions workflow (e.g., using Deploy PR Preview with a unique path per PR and co...

</details>



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

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

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

📍 Connect Copilot coding agent with [Jira](https://gh.io/cca-jira-docs), [Azure Boards](https://gh.io/cca-azure-boards-docs) or [Linear](https://gh.io/cca-linear-docs) to delegate work to Copilot in one click without leaving your project management tool.