Restrict deploy_sphinx_docs to main branch on manual workflow dispatch (#624)

* Restrict deploy_sphinx_docs to `main` branch on manual workflow dispatch

* Update deploy docs documentation

Author: lochhh

.github/workflows/docs_build_and_deploy.yml

@@ -2,9 +2,10 @@ name: Docs
 
 # Generate the documentation on all merges to main, all pull requests, or by
 # manual workflow dispatch. The build job can be used as a CI check that the
-# docs still build successfully. The deploy job only runs when a tag is
-# pushed and actually moves the generated html to the gh-pages branch
-# (which triggers a GitHub pages deployment).
+# docs still build successfully. The deploy job which moves the generated
+# html to the gh-pages branch and triggers a GitHub pages deployment
+# only runs when a tag is pushed or when the workflow is manually dispatched
+# from the main branch.
 on:
   push:
     branches:
@@ -19,7 +20,11 @@ jobs:
 
   linting:
     # scheduled workflows should not run on forks
-    if: (${{ github.event_name == 'schedule' }} && ${{ github.repository_owner == 'neuroinformatics-unit' }} && ${{ github.ref == 'refs/heads/main' }}) || (${{ github.event_name != 'schedule' }})
+    if: |
+      (github.event_name == 'schedule' &&
+      github.repository_owner == 'neuroinformatics-unit' &&
+      github.ref == 'refs/heads/main') ||
+      (github.event_name != 'schedule')
     runs-on: ubuntu-latest
     steps:
       - uses: neuroinformatics-unit/actions/lint@v2
@@ -45,7 +50,9 @@ jobs:
     needs: build_sphinx_docs
     permissions:
       contents: write
-    if: (github.event_name == 'push' && github.ref_type == 'tag') || github.event_name == 'workflow_dispatch'
+    if: |
+      (github.event_name == 'push' && github.ref_type == 'tag') ||
+      (github.event_name == 'workflow_dispatch' && github.ref == 'refs/heads/main')
     runs-on: ubuntu-latest
     steps:
       - uses: neuroinformatics-unit/actions/deploy_sphinx_docs@main

CONTRIBUTING.md

@@ -207,10 +207,9 @@ Other `.md`  or `.rst` files are linked to the homepage via the `toctree` direct
 We use [Sphinx](sphinx-doc:) and the [PyData Sphinx Theme](https://pydata-sphinx-theme.readthedocs.io/en/stable/index.html)
 to build the source files into HTML output.
 This is handled by a GitHub actions workflow (`.github/workflows/docs_build_and_deploy.yml`).
-The build job is triggered on each PR, ensuring that the documentation build is not broken by new changes.
-The deployment job is only triggered whenever a tag is pushed to the _main_ branch,
-ensuring that the documentation is published in sync with each PyPI release.
-
+The build job runs on each PR, ensuring that the documentation build is not broken by new changes.
+The deployment job runs on tag pushes (for PyPI releases) or manual triggers on the _main_ branch.
+This keeps the documentation aligned with releases, while allowing manual redeployment when necessary.
 
 ### Editing the documentation
 To edit the documentation, first clone the repository, and install `movement` in a