Print out details of how to configure repository to allow deploying docs in post_gen_project.py hook
#391
Assignees
Labels
enhancement
New feature or request
Comments
|
#205 was just meant to be in some way, currently there's a fair bit we assume |
matt-graham
added a commit
that referenced
this issue
Jun 6, 2024
…404) Fixes #391 Adds some text to be printed out in `post_gen_project.py` hook when `deploy_docs_to_github_pages` cookiecutter option is `True` to give instructions on how to complete set up of deployment of HTML documentation on GitHub Pages. Example output: ``` Initialized empty Git repository in /home/matt/projects/test-package/.git/ GitHub CLI detected, you can create a repo with the following: gh repo create matt-graham/test-package -d 'A cookiecutter package with UCL ARC recommendations.' --public -r origin --source test-package 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 https://github.com/matt-graham/test-package/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 https://github.com/matt-graham/test-package/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). ```
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Is Your Feature Request Related to a Problem? Please Describe
Currently if the
deploy_docs_to_github_pagestemplate option is set toy/Truethe documentation workflow will be set up to push the built documentation to a branchgh-pagesto allow deploying on GitHub Pages however we only document that additional steps are required to get this working this in a comment in the workflow. Specifically the repository needs to be configured inhttps://github.com/{{owner}}/{{project_slug}/settings/pagesto deploy GitHub Pages from the branchgh-pages(which will be created after first run of documentation workflow on push tomain) and (which is not currently documented) the permissions for GitHub Actions workflows need to be changed for the repository toRead and write permissionsinhttps://github.com/{{owner}}/{{project_slug}/settings/actions.Describe the Solution You'd Like
post_gen_projecthook which deals with theinitialise_empty_git_repositorytemplate option to also output instructions to the user to update repository settings as above ifdeploy_docs_to_github_pagesis set toTrue.Describe Alternatives You've Considered
#205 suggests documenting next steps such as this - I'm assuming this means in the repository README? I think that would also be good to have but I think having something similar to the behaviour for
initialise_empty_git_repositorywould be good.Additional Context
No response
The text was updated successfully, but these errors were encountered: