Merge branch 'main' into sc/tox-warnings-on-freshly-cut-cookie

Author: samcunliffe

README.md

@@ -55,9 +55,11 @@ cd example-research-software-project
 git init
 # uv venv
 # source .venv/bin/activate
-uv pip install -e ".[dev]"
+uv sync
 ```
 
+Note that `uv>=0.6.7` is required to use the `--group` option.
+
 <!-- links here -->
 
 <!-- prettier-ignore-start -->

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

tests/data/test_package_generation/pyproject.toml

@@ -5,6 +5,27 @@ requires = [
     "setuptools-scm",
 ]
 
+[dependency-groups]
+dev = [
+    "build",
+    "mypy",
+    "pre-commit",
+    "ruff",
+    "tox",
+    "twine",
+]
+docs = [
+    "mkdocs",
+    "mkdocs-include-markdown-plugin",
+    "mkdocs-material",
+    "mkdocstrings",
+    "mkdocstrings-python",
+]
+test = [
+    "pytest",
+    "pytest-cov",
+]
+
 [project]
 authors = [
     {email = "eva.lu.ator@ucl.ac.uk", name = "Eva Lu Ator"},
@@ -31,23 +52,6 @@ license-files = [
     "LICENSE.md",
 ]
 name = "cookiecutter-test"
-optional-dependencies = {dev = [
-    "build",
-    "mypy",
-    "pre-commit",
-    "ruff",
-    "tox",
-    "twine",
-], docs = [
-    "mkdocs",
-    "mkdocs-include-markdown-plugin",
-    "mkdocs-material",
-    "mkdocstrings",
-    "mkdocstrings-python",
-], test = [
-    "pytest",
-    "pytest-cov",
-]}
 readme = "README.md"
 requires-python = ">=3.11"
 urls.homepage = "https://github.com/test-user/cookiecutter-test"
@@ -126,7 +130,7 @@ env_run_base = {commands = [
         "--cov",
         "--cov-report=xml",
     ],
-], extras = [
+], dependency_groups = [
     "test",
 ]}
 env.docs = {commands = [
@@ -135,7 +139,7 @@ env.docs = {commands = [
         "build",
         "--strict",
     ],
-], extras = [
+], dependency_groups = [
     "docs",
 ]}
 gh.python."3.11" = ["py311"]

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.
+- 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.
 
-- Set `Source` to `Deploy from branch` and `Branch` to `gh-pages`.
-
-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
@@ -309,10 +293,10 @@ uv venv --python 3.11.6
 Once you have created and activated a virtual environment for the project, you can install the package in [editable mode](https://setuptools.pypa.io/en/latest/userguide/development_mode.html), along with both its required dependencies and optional sets of dependencies for development (`dev`), documentation (`docs`) and testing (`test`) by running
 
 ```sh
-uv pip install --editable ".[dev,docs,test]"
+uv sync --all-groups
 ```
 
-from the root of the project repository.
+from the root of the project repository. Note that `uv>=0.6.7` is required to use the `--group` option.
 
 <details><summary>Using venv as an alternative to uv </summary> <!-- markdownlint-disable-line MD033 -->
 
@@ -343,9 +327,11 @@ python -m pip install --upgrade pip
 Similar to `uv`, once the environment is active, you can install the package in editable mode as well as all dependencies:
 
 ```sh
-python -m pip install --editable ".[dev,docs,test]"
+python -m pip install --editable . --group dev --group docs --group test
 ```
 
+Note that `pip>=25.1` is required to use the `--group` option.
+
 </details>
 
 ## 🧪 Running package tests locally

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

{{cookiecutter.project_slug}}/pyproject.toml

@@ -5,6 +5,27 @@ requires = [
     "setuptools-scm",
 ]
 
+[dependency-groups]
+dev = [
+    "build",
+    "mypy",
+    "pre-commit",
+    "ruff",
+    "tox",
+    "twine",
+]
+docs = [
+    "mkdocs",
+    "mkdocs-include-markdown-plugin",
+    "mkdocs-material",
+    "mkdocstrings",
+    "mkdocstrings-python",
+]
+test = [
+    "pytest",
+    "pytest-cov",
+]
+
 [project]
 authors = [
     {email = "{{cookiecutter.author_email}}", name = "{{cookiecutter.author_given_names}} {{cookiecutter.author_family_names}}"},
@@ -34,23 +55,6 @@ license-files = [
     "LICENSE.md",
 ]
 name = "{{cookiecutter.project_slug}}"
-optional-dependencies = {dev = [
-    "build",
-    "mypy",
-    "pre-commit",
-    "ruff",
-    "tox",
-    "twine",
-], docs = [
-    "mkdocs",
-    "mkdocs-include-markdown-plugin",
-    "mkdocs-material",
-    "mkdocstrings",
-    "mkdocstrings-python",
-], test = [
-    "pytest",
-    "pytest-cov",
-]}
 readme = "README.md"
 requires-python = ">={{cookiecutter.min_python_version}}"
 urls.homepage = "{{cookiecutter.__repo_url}}"
@@ -132,7 +136,7 @@ env_run_base = {commands = [
         "--cov",
         "--cov-report=xml",
     ],
-], extras = [
+], dependency_groups = [
     "test",
 ]}
 env.docs = {commands = [
@@ -141,7 +145,7 @@ env.docs = {commands = [
         "build",
         "--strict",
     ],
-], extras = [
+], dependency_groups = [
     "docs",
 ]}
 {%- for python_version in range(