Use actions/deploy-pages to deploy docs in template (#578)

Resolves #561 
Resolve #574 

Switches from the current branch based workflow for deploying MkDocs
documentation to GitHub Pages in template to instead use
`actions/deploy-pages` and removes suggestion in post-generation message
displayed to user to set repository wide write permissions for Github
Actions workflows in favour of using granular permissions in workflow
file.

I originally completely removed the post-generation message as I thought
by using the `actions/deploy-pages` approach we might be able to avoid
having to do additional configuration of repository before site will
deploy, but unfortunately it seems the default source setting for GitHub
Pages on a new repository is branch so unless this is switched to GitHub
Actions before doing the initial workflow run, the deploy job fails. I
couldn't see any options for configuring this via CLI under `gh repo
edit`.

Tested this works at https://github.com/matt-graham/docs-deploy-test and
everything seems to work as expected provided manual configuration steps
are done as indicated in updated message.

Author: matt-graham

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

tutorial.md

@@ -189,60 +189,44 @@ When you pushed to `main` you will have triggered runs of the [GitHub actions](h
 You can view the status of the workflow jobs by browsing the `Actions` button at the top bar of the repository homepage, which takes you to `https://github.com/{github_owner}/{project_slug}/actions`.
 
 Depending on your account settings, you may find that the `Documentation` workflow shows as failed (❌).
-If you see this it's probably because of the repository permissions settings for GitHub Actions.
+If you see this it's probably because of the repository setting specifying the source for deploying a GitHub pages site from.
 We'll fix this in the next section.
 
 For now, have a browse around the GitHub web interface.
 
 ## 📄 Configuring repository to host docs on GitHub Pages
 
-Now that your repository is on GitHub, you need to do a few more steps to set up your project's documentation website.
+Now that your repository is on GitHub, you need to do one more step to set up your project's documentation website.
 The HTML documentation will be built using the `Documentation` workflow (that we're going to fix) and hosted on [GitHub Pages](https://pages.github.com/).
 
 If you scroll back in your terminal to the end of the [cookiecutter] questions, you should be able to find a message like:
 
 ```sh
-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
+The 'Documentation' GitHub Actions workflow has been set up to deploy the built
+HTML documentation to a GitHub Pages website on pushes to main.
 
-https://github.com/{github_owner}/{project_slug}/settings/actions
-
-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
+You will need to configure the repository to deploy a GitHub pages site using
+GitHub Actions by going to
 
 https://github.com/{github_owner}/{project_slug}/settings/pages
 
-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'.
 ```
 
 As before replace `{github_owner}` and `{project_slug}` with the relevant GitHub repository owner and project slug that you chose at the start.
 
-The first part of the instructions explains how to set the permissions for GitHub Actions.
-This lets the Actions bot push the built HTML documentation to a branch `gh-pages` when you update the default `main` branch.
+Following tha instructions printed to the terminal, go to `https://github.com/{github_owner}/{project_slug}/settings/pages` and set GitHub Actions as the source for GitHub Pages.
 
-- Go to the Actions settings page at the URL above (or via the repository `Settings` tab, then `Actions > General`).
-- Set `Workflow permissions` to `Read and write permissions`.
+- Set `Source` to `GitHub Actions`.
 
-Now that the permissions have changed, we need to re-run the `Documentation` workflow.
+Now that the source settings has been changed, we need to re-run the `deploy` job in the `Documentation` workflow.
 
 - Go back to the Actions page. Select the Actions button (in the top bar), or visit
   `https://github.com/{github_owner}/{project_slug}/actions`.
 - Click on the failing entry for the `Documentation` workflow.
-- Click on the `Re-run all jobs` button (top right of the page).
-
-After the `Documentation` workflow finishes, a new `gh-pages` branch will be created containing only the HTML docs.
-
-Following tha instructions printed to the terminal, go to `https://github.com/{github_owner}/{project_slug}/settings/pages` and set this branch as the source for GitHub Pages.
-
-- Set `Source` to `Deploy from branch` and `Branch` to `gh-pages`.
+- Click on the drop down ▼ symbol next to `Re-run jobs` button (top right of the page) and click `Re-run failed jobs`.
+- Click `Re-run jobs` button in dialogue box which appears which should list the `deploy` job as the failed job to re-run.
 
-This will start another new workflow called `pages-build-deployment` (in the Actions page).
 When it finishes, you can view your HTML docs at:
 
 ```sh

{{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 %}