Use actions/deploy-pages to deploy docs in template

hooks/post_gen_project.py

@@ -86,19 +86,12 @@ def main(initialise_git_repository: str, deploy_docs_to_github_pages: str) -> in
             return _EXIT_FAILURE
     if deploy_docs_to_github_pages == "True":
         print(
-            "The 'Documentation' GitHub Actions workflow has been set up to push the "
-            "built HTML documentation to a branch gh-pages on pushes to main for "
-            "deploying as a GitHub Pages website. To allow the GitHub Actions bot to "
-            "push to the gh-pages branch you need to enable 'Read and write "
-            "permissions' under 'Workflow permissions' at\n\n"
-            "{{cookiecutter.__repo_url}}/settings/actions\n\n"
-            "After the 'Documentation' workflow has successfully completed at least "
-            "once you will also need to configure the repository to deploy a GitHub "
-            "pages site from the content on the gh-pages branch by going to\n\n"
+            "The 'Documentation' GitHub Actions workflow has been set up to deploy the "
+            "built HTML documentation to a GitHub Pages website on pushes to main. \n\n"
+            "You will need to configure the repository to deploy a GitHub pages site "
+            "using GitHub Actions by going to\n\n"
             "{{cookiecutter.__repo_url}}/settings/pages\n\n"
-            "and under 'Built and deployment' selecting 'Deploy from a branch' for "
-            "the 'Source' drop-down and 'gh-pages' for the 'Branch' drop-down, "
-            "leaving the branch path drop-down with its default value of '/ (root)'.",
+            "and under 'Build and deployment' selecting 'GitHub Actions' for 'Source'.",
         )
 
     return _EXIT_SUCCESS

tests/data/test_package_generation/.github/workflows/docs.yml

@@ -7,7 +7,7 @@ on:
   pull_request:
 
 jobs:
-  docs:
+  build:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout source
@@ -28,19 +28,26 @@ jobs:
 
       - name: Install tox
         run: python -m pip install tox
+
       - name: Build HTML documentation with tox
         run: tox -e docs
 
-      # Automatically deploy documentation to a GitHub Pages website on pushing to main.
-      # Requires configuring the repository to deploy GitHub pages from a branch
-      # gh-pages (https://tinyurl.com/gh-pages-from-branch), which will be created the
-      # first time this workflow step is run.
-      - name: Publish documentation on GitHub pages
-        if: success() && github.event_name != 'pull_request'
-        uses: peaceiris/actions-gh-pages@4f9cc6602d3f66b9c108549d475ec49e8ef4d45e # v4
+      - name: Upload built docs as artifact
+        id: deployment
+        uses: actions/upload-pages-artifact@56afc609e74202658d3ffba0e8f6dda462b719fa # v3
         with:
-          github_token: ${{  secrets.GITHUB_TOKEN }}
-          publish_dir: site
-          publish_branch: gh-pages
-          user_name: "github-actions[bot]"
-          user_email: "github-actions[bot]@users.noreply.github.com"
+          path: site
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    permissions:
+      pages: write
+      id-token: write
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4

{{cookiecutter.project_slug}}/.github/workflows/docs.yml

@@ -7,7 +7,7 @@ on:
   pull_request:
 
 jobs:
-  docs:
+  build:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout source
@@ -28,21 +28,27 @@ jobs:
 
       - name: Install tox
         run: python -m pip install tox
+
       - name: Build HTML documentation with tox
         run: tox -e docs
-{%- if cookiecutter.deploy_docs_to_github_pages %}
 
-      # Automatically deploy documentation to a GitHub Pages website on pushing to main.
-      # Requires configuring the repository to deploy GitHub pages from a branch
-      # gh-pages (https://tinyurl.com/gh-pages-from-branch), which will be created the
-      # first time this workflow step is run.
-      - name: Publish documentation on GitHub pages
-        if: success() && github.event_name != 'pull_request'
-        uses: peaceiris/actions-gh-pages@4f9cc6602d3f66b9c108549d475ec49e8ef4d45e # v4
+      - name: Upload built docs as artifact
+        id: deployment
+        uses: actions/upload-pages-artifact@56afc609e74202658d3ffba0e8f6dda462b719fa # v3
         with:
-          github_token: ${{ '{{' }}  secrets.GITHUB_TOKEN {{ '}}' }}
-          publish_dir: site
-          publish_branch: gh-pages
-          user_name: "github-actions[bot]"
-          user_email: "github-actions[bot]@users.noreply.github.com"
+          path: site
+{% if cookiecutter.deploy_docs_to_github_pages %}
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ '{{' }} steps.deployment.outputs.page_url {{ '}}' }}
+    permissions:
+      pages: write
+      id-token: write
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4
 {%- endif %}