Use granular `GITHUB_TOKEN` permissions in template docs workflow

[matt-graham]

Is Your Feature Request Related to a Problem? Please Describe

Currently there is a post generation hook which prints a message if users selected to set up deploying the documentation to GitHub pages, which recommends to users to set the repository wide GITHUB_TOKEN permissions to read-write

python-tooling/hooks/post_gen_project.py

Lines 88 to 102 in f1a228d

	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)'."
	)

This is a bad idea from a security standpoint (my fault as I originally wrote this message!) as it grants write permissions to all workflow jobs in the repository.

Describe the Solution You'd Like

It would be better to give the required write permissions only at a more granular level of the actual workflow job by adding a

    permissions:
      contents: write

block under the job in the templated workflow YAML file.

Describe Alternatives You've Considered

Resolving #561 would probably also close this issue as if we follow the recommended actions/deploy-pages GitHub Action set up we will set up granular permissions for the deploy to pages to job in the workflow file, but we will still need to remember to remove the post-generation message!

Additional Context

Tagging @jamesbriant as he originally noted this issue and suggested fix after we used template to set up docs in https://github.com/jamesbriant/koh-gpjax/.

[samcunliffe]

@all-contributors please add @jamesbriant for bug

[allcontributors]

@samcunliffe

I've put up a pull request to add @jamesbriant! 🎉

[allcontributors]

@samcunliffe

I've put up a pull request to add @K-Meech! 🎉