From a83f7142cd5aee4a7d69d6261baa17fedbba34ec Mon Sep 17 00:00:00 2001 From: Matt Graham Date: Wed, 23 Jul 2025 11:28:39 +0100 Subject: [PATCH 1/8] Use action/deploy-pages to deploy docs in template --- .../.github/workflows/docs.yml | 35 +++++++++++-------- 1 file changed, 21 insertions(+), 14 deletions(-) diff --git a/{{cookiecutter.project_slug}}/.github/workflows/docs.yml b/{{cookiecutter.project_slug}}/.github/workflows/docs.yml index efca9a16..039777bb 100644 --- a/{{cookiecutter.project_slug}}/.github/workflows/docs.yml +++ b/{{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,28 @@ 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 %} From c89707500264dce23673939616bf32ebd6013e78 Mon Sep 17 00:00:00 2001 From: Matt Graham Date: Wed, 23 Jul 2025 11:30:05 +0100 Subject: [PATCH 2/8] Remove obsolete post-generation message --- hooks/post_gen_project.py | 27 ++------------------------- 1 file changed, 2 insertions(+), 25 deletions(-) diff --git a/hooks/post_gen_project.py b/hooks/post_gen_project.py index ac978c86..735963f3 100644 --- a/hooks/post_gen_project.py +++ b/hooks/post_gen_project.py @@ -7,13 +7,12 @@ _EXIT_SUCCESS = 0 -def main(initialise_git_repository: str, deploy_docs_to_github_pages: str) -> int: +def main(initialise_git_repository: str) -> int: """ Create a git repository on generation of the project. Args: initialise_git_repository: Whether to initialise the repo - deploy_docs_to_github_pages: Whether to deploy built docs to GitHub Pages Returns: The return code of the process @@ -84,30 +83,8 @@ def main(initialise_git_repository: str, deploy_docs_to_github_pages: str) -> in # some other error print(f"There was an error with the GitHub CLI: {e.returncode}\n{e.stderr}") 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" - "{{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)'." - ) - return _EXIT_SUCCESS if __name__ == "__main__": - sys.exit( - main( - "{{ cookiecutter.initialise_git_repository }}", - "{{ cookiecutter.deploy_docs_to_github_pages }}", - ) - ) + sys.exit(main("{{ cookiecutter.initialise_git_repository }}")) From 7f763fd57af3c0dd65a56a19db3620eed2874311 Mon Sep 17 00:00:00 2001 From: Matt Graham Date: Wed, 23 Jul 2025 11:47:38 +0100 Subject: [PATCH 3/8] Adjust whitespacing in templated workflow file --- {{cookiecutter.project_slug}}/.github/workflows/docs.yml | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/{{cookiecutter.project_slug}}/.github/workflows/docs.yml b/{{cookiecutter.project_slug}}/.github/workflows/docs.yml index 039777bb..692408da 100644 --- a/{{cookiecutter.project_slug}}/.github/workflows/docs.yml +++ b/{{cookiecutter.project_slug}}/.github/workflows/docs.yml @@ -37,8 +37,7 @@ jobs: uses: actions/upload-pages-artifact@56afc609e74202658d3ffba0e8f6dda462b719fa # v3 with: path: site - -{%- if cookiecutter.deploy_docs_to_github_pages %} +{% if cookiecutter.deploy_docs_to_github_pages %} deploy: environment: name: github-pages From 900991d8b661eea047a0e54881f14996e85b002d Mon Sep 17 00:00:00 2001 From: Matt Graham Date: Wed, 23 Jul 2025 11:49:44 +0100 Subject: [PATCH 4/8] Revert "Remove obsolete post-generation message" This reverts commit c89707500264dce23673939616bf32ebd6013e78. --- hooks/post_gen_project.py | 27 +++++++++++++++++++++++++-- 1 file changed, 25 insertions(+), 2 deletions(-) diff --git a/hooks/post_gen_project.py b/hooks/post_gen_project.py index 735963f3..ac978c86 100644 --- a/hooks/post_gen_project.py +++ b/hooks/post_gen_project.py @@ -7,12 +7,13 @@ _EXIT_SUCCESS = 0 -def main(initialise_git_repository: str) -> int: +def main(initialise_git_repository: str, deploy_docs_to_github_pages: str) -> int: """ Create a git repository on generation of the project. Args: initialise_git_repository: Whether to initialise the repo + deploy_docs_to_github_pages: Whether to deploy built docs to GitHub Pages Returns: The return code of the process @@ -83,8 +84,30 @@ def main(initialise_git_repository: str) -> int: # some other error print(f"There was an error with the GitHub CLI: {e.returncode}\n{e.stderr}") 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" + "{{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)'." + ) + return _EXIT_SUCCESS if __name__ == "__main__": - sys.exit(main("{{ cookiecutter.initialise_git_repository }}")) + sys.exit( + main( + "{{ cookiecutter.initialise_git_repository }}", + "{{ cookiecutter.deploy_docs_to_github_pages }}", + ) + ) From 84c2e61ec94adb7063dedd383846d46cd2c1f522 Mon Sep 17 00:00:00 2001 From: Matt Graham Date: Wed, 23 Jul 2025 12:01:27 +0100 Subject: [PATCH 5/8] Update post-generation message to only mention selecting GH Pages source --- hooks/post_gen_project.py | 17 +++++------------ 1 file changed, 5 insertions(+), 12 deletions(-) diff --git a/hooks/post_gen_project.py b/hooks/post_gen_project.py index ac978c86..a3541323 100644 --- a/hooks/post_gen_project.py +++ b/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 From a5225ade5a5f551dfdca8e902a5e4bba5dbe4636 Mon Sep 17 00:00:00 2001 From: Matt Graham Date: Wed, 23 Jul 2025 13:53:54 +0100 Subject: [PATCH 6/8] Update package generation reference data --- .../.github/workflows/docs.yml | 33 +++++++++++-------- 1 file changed, 20 insertions(+), 13 deletions(-) diff --git a/tests/data/test_package_generation/.github/workflows/docs.yml b/tests/data/test_package_generation/.github/workflows/docs.yml index 36e639b0..6b7d5427 100644 --- a/tests/data/test_package_generation/.github/workflows/docs.yml +++ b/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 From e584221ce18c1b515658650c4d554f3bfc2b4573 Mon Sep 17 00:00:00 2001 From: Matt Graham Date: Wed, 23 Jul 2025 14:44:32 +0100 Subject: [PATCH 7/8] Update tutorial with new GH Pages deploy process --- tutorial.md | 40 ++++++++++++---------------------------- 1 file changed, 12 insertions(+), 28 deletions(-) diff --git a/tutorial.md b/tutorial.md index f4c2ee78..70993040 100644 --- a/tutorial.md +++ b/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 'Built 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 From f7a85b9a85e9e07452bb662483f7ef8b151f39a1 Mon Sep 17 00:00:00 2001 From: Matt Graham Date: Wed, 23 Jul 2025 14:48:55 +0100 Subject: [PATCH 8/8] Correct typo in tutorial.md --- tutorial.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tutorial.md b/tutorial.md index 70993040..8279b05c 100644 --- a/tutorial.md +++ b/tutorial.md @@ -210,7 +210,7 @@ GitHub Actions by going to https://github.com/{github_owner}/{project_slug}/settings/pages -and under 'Built and deployment' selecting 'GitHub Actions' for 'Source'. +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.