Skip to content

Commit

Permalink
Renaming github_username to github_owner + generating `__repo_nam…
Browse files Browse the repository at this point in the history
…e` & `__repo_url` (#409)

Though its not exposed to user now we have longer prompts rather than
using variable names directly, I think `github_username` is a bit of a
misnomer given that it can be either a user or organization name, hence
I think `github_owner` would be a better choice.

We also currently manually construct the GitHub repository URL in lots
of different bits of the template and also the qualified repository name
in a few places. We can use [double underscore prefixed (rendered)
private
variables](https://cookiecutter.readthedocs.io/en/stable/advanced/private_variables.html)
in the cookiecutter config to generate the repository URL and qualified
name once and then reuse elsewhere to avoid the repetition. This would
also make it simpler to later switch to supporting alternative
repository hosting options such as GitLab in future (which is the
rational for naming the variables `__repo_name` and `__repo_url` rather
than `__github_repo_name` and `__github_repo_url`).

---------

Co-authored-by: Patrick J. Roddy <[email protected]>
Co-authored-by: David Stansby <[email protected]>
  • Loading branch information
3 people authored Nov 5, 2024
1 parent d5b41c7 commit 85b0b29
Show file tree
Hide file tree
Showing 9 changed files with 41 additions and 41 deletions.
6 changes: 4 additions & 2 deletions cookiecutter.json
Original file line number Diff line number Diff line change
Expand Up @@ -8,11 +8,13 @@
"project_short_description": "A cookiecutter package with UCL ARC recommendations.",
"initialise_git_repository": true,
"deploy_docs_to_github_pages": true,
"github_username": "{{cookiecutter.author_given_names.lower().replace(' ', '-')}}-{{cookiecutter.author_family_names.lower().replace(' ', '-')}}",
"github_owner": "{{cookiecutter.author_given_names.lower().replace(' ', '-')}}-{{cookiecutter.author_family_names.lower().replace(' ', '-')}}",
"min_python_version": ["3.11", "3.12", "3.13"],
"max_python_version": ["3.13", "3.12", "3.11"],
"license": ["MIT", "BSD-3", "GPL-3.0"],
"funder": "",
"__repo_name": "{{cookiecutter.github_owner}}/{{cookiecutter.project_slug}}",
"__repo_url": "https://github.com/{{cookiecutter.__repo_name}}",
"__prompts__": {
"author_given_names": "Given name(s) of package author",
"author_family_names": "Family name(s) of package author",
Expand All @@ -23,7 +25,7 @@
"project_short_description": "Short description of the project",
"initialise_git_repository": "Initialise project directory as a Git repository?",
"deploy_docs_to_github_pages": "Automatically deploy HTML docs to GitHub Pages on pushes to main?",
"github_username": "GitHub user or organization name which will be owner of repository",
"github_owner": "GitHub user or organization name which will be owner of repository",
"min_python_version": "Minimum Python version supported by package",
"max_python_version": "Maximum Python version supported by package",
"license": "Which open-source license to release package under",
Expand Down
12 changes: 5 additions & 7 deletions hooks/post_gen_project.py
Original file line number Diff line number Diff line change
Expand Up @@ -62,7 +62,7 @@ def main(initialise_git_repository: str, deploy_docs_to_github_pages: str) -> in
print(
"GitHub CLI detected, you can create a repo with the following:\n\n"
"gh repo create "
"{{cookiecutter.github_username}}/{{cookiecutter.project_slug}} "
"{{cookiecutter.__repo_name}} "
'-d "{{cookiecutter.project_short_description}}" '
"--public "
"-r origin "
Expand All @@ -73,12 +73,12 @@ def main(initialise_git_repository: str, deploy_docs_to_github_pages: str) -> in
print(
"You now have a local git repository. To sync this to GitHub "
"you need to create an empty GitHub repo with the name "
"{{cookiecutter.github_username}}/{{cookiecutter.project_slug}} "
"{{cookiecutter.__repo_name}} "
"- DO NOT SELECT ANY OTHER OPTION.\n\nSee this link for more detail "
"https://docs.github.com/en/get-started/quickstart/create-a-repo.\n\n"
"Then run:\n\n"
"git remote add origin [email protected]:"
"{{cookiecutter.github_username}}/{{cookiecutter.project_slug}}.git\n"
"{{cookiecutter.__repo_name}}.git\n"
)
except subprocess.CalledProcessError as e:
# some other error
Expand All @@ -91,13 +91,11 @@ def main(initialise_git_repository: str, deploy_docs_to_github_pages: str) -> in
"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"
"https://github.com/{{cookiecutter.github_username}}/"
"{{cookiecutter.project_slug}}/settings/actions\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"
"https://github.com/{{cookiecutter.github_username}}/"
"{{cookiecutter.project_slug}}/settings/pages\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)'."
Expand Down
8 changes: 4 additions & 4 deletions tests/test_git_init.py
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ def test_initialisation_of_git_repo(
) -> None:
"""Checks to see if git was correctly initialised if desired."""
test_config = {
"github_username": "test-user",
"github_owner": "test-user",
"project_short_description": "description",
"project_name": "Cookiecutter Test",
"initialise_git_repository": initialise_git_repository,
Expand Down Expand Up @@ -57,7 +57,7 @@ def test_initialisation_of_git_repo(
)
assert (
"GitHub CLI detected, you can create a repo with the following:\n\n"
f"gh repo create {test_config['github_username']}/"
f"gh repo create {test_config['github_owner']}/"
f"cookiecutter-test -d "
f"\"{test_config['project_short_description']}\" --public -r "
f"origin --source cookiecutter-test" in result.stdout
Expand All @@ -69,11 +69,11 @@ def test_initialisation_of_git_repo(
assert (
"You now have a local git repository. To sync this to GitHub you "
"need to create an empty GitHub repo with the name "
f"{test_config['github_username']}/"
f"{test_config['github_owner']}/"
f"cookiecutter-test - DO NOT SELECT ANY "
"OTHER OPTION.\n\nSee this link for more detail "
"https://docs.github.com/en/get-started/quickstart/create-a-repo"
".\n\nThen run:\n\ngit remote add origin [email protected]:"
f"{test_config['github_username']}/"
f"{test_config['github_owner']}/"
f"cookiecutter-test.git" in result.stdout
)
6 changes: 3 additions & 3 deletions tests/test_package_generation.py
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ def test_package_generation(
) -> None:
"""Test package generation."""
test_config = {
"github_username": "test-user",
"github_owner": "test-user",
"project_short_description": "description",
"project_name": "Cookiecutter Test",
# Not having a git repo makes it easier to check in/out reference
Expand Down Expand Up @@ -98,7 +98,7 @@ def test_pip_installable(
) -> None:
"""Test generated package is pip installable."""
test_config = {
"github_username": "test-user",
"github_owner": "test-user",
"project_short_description": "description",
"project_name": "Cookiecutter Test",
}
Expand Down Expand Up @@ -129,7 +129,7 @@ def test_optional_funder(
) -> None:
"""Test package generation."""
config = {
"github_username": "test-user",
"github_owner": "test-user",
"project_short_description": "description",
"project_name": "Cookiecutter Test",
"funder": funder,
Expand Down
24 changes: 12 additions & 12 deletions tutorial.md
Original file line number Diff line number Diff line change
Expand Up @@ -153,19 +153,19 @@ When you completed setting up the package using the `cookiecutter` command you s
```sh
GitHub CLI detected, you can create a repo with the following:

gh repo create {github_user}/{project_slug} -d "{project_description}" --public -r origin --source {project_slug}
gh repo create {github_owner}/{project_slug} -d "{project_description}" --public -r origin --source {project_slug}
```

where `{github_user}`, `{project_slug}` and `{project_description}` are replaced with the relevant GitHub user name, project slug and description that you entered when setting up the package using `cookiecutter`. You should now copy-paste and run the `gh repo create ...` command that was printed out in the message - if you no longer have access to the message you can use the example above, being careful to subsitute the placeholders in braces `{}` with the relevant values.
where `{github_owner}`, `{project_slug}` and `{project_description}` are replaced with the relevant GitHub repository owner (user name), project slug and description that you entered when setting up the package using `cookiecutter`. You should now copy-paste and run the `gh repo create ...` command that was printed out in the message - if you no longer have access to the message you can use the example above, being careful to subsitute the placeholders in braces `{}` with the relevant values.

If you get an error message at this point it may be because you have not installed the GitHub CLI or set up the authorisation for the GitHub CLI as [described in the setup instructions above](#%EF%B8%8F-setting-up-dependencies-for-using-template).

If the command runs successfully you should see a message of the form

```sh
✓ Created repository {github_user}/{project_slug} on GitHub
https://github.com/{github_user}/{project_slug}
✓ Added remote https://github.com/{github_user}/{project_slug}.git
✓ Created repository {github_owner}/{project_slug} on GitHub
https://github.com/{github_owner}/{project_slug}
✓ Added remote https://github.com/{github_owner}/{project_slug}.git
```

A repository should have been created at the printed URL which you should be able to navigate to in your browser (either copy-paste in to browser or depending on terminal application you may be able to hold `Ctrl` and click on URL directly). Currently both the remote and local repositories are empty as we have not made any commits.
Expand All @@ -181,7 +181,7 @@ git push --set-upstream origin main

If you now navigate to the GitHub repository URL in your browser you should see the package files present, with the content of the top-level `README.md` being displayed as the repository landing page.

The push of the initial commit to the default `main` branch will have also triggered runs of the GitHub Actions workflows set up in the repository. You can view the status of the workflow job runs by opening the `Actions` pane from the top navigation bar on the repository landing page, or going to the URL `https://github.com/{github_user}/{project_slug}/actions`.
The push of the initial commit to the default `main` branch will have also triggered runs of the GitHub Actions workflows set up in the repository. You can view the status of the workflow job runs by opening the `Actions` pane from the top navigation bar on the repository landing page, or going to the URL `https://github.com/{github_owner}/{project_slug}/actions`.

Depending on your account settings, you may find that the `Documentation` workflow shows as failed (❌). If this is the case this is likely because the repository has been set by default to only allow GitHub Actions workflows read permissions on the repository, which prevents the step in the `Documentation` workflow which pushes the built HTML documentation to a branch `gh-pages` from completing. In the next section we will look at how to configure the repository to ensure the permissions are set correctly and have the HTML documentation deployed to a GitHub Pages website.

Expand All @@ -196,27 +196,27 @@ 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/{github_user}/{project_slug}/settings/actions
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

https://github.com/{github_user}/{project_slug}/settings/pages
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)'.
```

where as before `{github_user}` and `{project_slug}` are replaced with the relevant GitHub user name and project slug that you entered when setting up the package.
where as before `{github_owner}` and `{project_slug}` are replaced with the relevant GitHub repository owner and project slug that you entered when setting up the package.

The first part of the instructions gives details of how to set the permissions for GitHub Actions workflows in the repository to allow the GitHub Actions bot to push the built HTML documentation to a branch `gh-pages` on updates to the default `main` branch on the repository, so that the documentation is automatically updated whenever changes are merged in to `main`. After going to the Actions settings page at the URL indicated (which can also be reached by going to the `Settings` tab in the top navigation bar of the repository and then selecting `Action > General` in the left hand navigation menu) and ensuring `Workflow permissions` is set to allow `Read and write permissions`, if you have changed the permissions you will also need to re-run the documentation workflow with the updated permissions. This can be done by going to the Actions pane in the repository (accessible from top navigation bar or by going to `https://github.com/{github_user}/{project_slug}/actions`), clicking on the (top / latest if there are multiple) entry for the _Documentation_ workflow, which should be showing as failing, and then from the resulting page click the `Re-run all jobs` button.
The first part of the instructions gives details of how to set the permissions for GitHub Actions workflows in the repository to allow the GitHub Actions bot to push the built HTML documentation to a branch `gh-pages` on updates to the default `main` branch on the repository, so that the documentation is automatically updated whenever changes are merged in to `main`. After going to the Actions settings page at the URL indicated (which can also be reached by going to the `Settings` tab in the top navigation bar of the repository and then selecting `Action > General` in the left hand navigation menu) and ensuring `Workflow permissions` is set to allow `Read and write permissions`, if you have changed the permissions you will also need to re-run the documentation workflow with the updated permissions. This can be done by going to the Actions pane in the repository (accessible from top navigation bar or by going to `https://github.com/{github_owner}/{project_slug}/actions`), clicking on the (top / latest if there are multiple) entry for the _Documentation_ workflow, which should be showing as failing, and then from the resulting page click the `Re-run all jobs` button.

Once the _Documentation_ workflow has successfully completed, a new branch `gh-pages` should have been created in the repository containing the HTML documentation. The second part of the instructions printed in the message output by the `cookiecutter` command indicate to go to a URL `https://github.com/{github_user}/{project_slug}/settings/pages` to set this branch as the source for a GitHub Pages website for the repository. If you now follow those instructions, setting the `Source` to `Deploy from branch` and `Branch` to `gh-pages`, the a new Actions workflow `pages-build-deployment` will be automatically triggered. Once this workflow has completed, you should be able to view the HTML documentation for the repository at a URL
Once the _Documentation_ workflow has successfully completed, a new branch `gh-pages` should have been created in the repository containing the HTML documentation. The second part of the instructions printed in the message output by the `cookiecutter` command indicate to go to a URL `https://github.com/{github_owner}/{project_slug}/settings/pages` to set this branch as the source for a GitHub Pages website for the repository. If you now follow those instructions, setting the `Source` to `Deploy from branch` and `Branch` to `gh-pages`, the a new Actions workflow `pages-build-deployment` will be automatically triggered. Once this workflow has completed, you should be able to view the HTML documentation for the repository at a URL

```sh
https://{github_user}.github.io/{project_slug}
https://{github_owner}.github.io/{project_slug}
```

The index page of the documentation reproduces the content from the repository README file. The documentation site also importantly includes _application programming interface_ (API) reference documentation built from the [docstrings](https://peps.python.org/pep-0257/#what-is-a-docstring) in the package source code; this API documentation is accessible from the `API reference` link in the navigation.
Expand Down
2 changes: 1 addition & 1 deletion {{cookiecutter.project_slug}}/CITATION.cff
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,6 @@ authors:
- family-names: "{{cookiecutter.author_family_names }}"
given-names: "{{ cookiecutter.author_given_names }}"
email: "{{ cookiecutter.author_email }}"
repository-code: "https://github.com/{{ cookiecutter.github_username }}/{{ cookiecutter.project_slug }}"
repository-code: "{{ cookiecutter.__repo_url }}"
title: "{{ cookiecutter.project_name }}: {{ cookiecutter.project_short_description }}"
license: "{{ cookiecutter.license }}"
16 changes: 8 additions & 8 deletions {{cookiecutter.project_slug}}/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,12 +7,12 @@
[![License][license-badge]](./LICENSE.md)

<!-- prettier-ignore-start -->
[tests-badge]: https://github.com/{{cookiecutter.github_username}}/{{cookiecutter.project_slug}}/actions/workflows/tests.yml/badge.svg
[tests-link]: https://github.com/{{cookiecutter.github_username}}/{{cookiecutter.project_slug}}/actions/workflows/tests.yml
[linting-badge]: https://github.com/{{cookiecutter.github_username}}/{{cookiecutter.project_slug}}/actions/workflows/linting.yml/badge.svg
[linting-link]: https://github.com/{{cookiecutter.github_username}}/{{cookiecutter.project_slug}}/actions/workflows/linting.yml
[documentation-badge]: https://github.com/{{cookiecutter.github_username}}/{{cookiecutter.project_slug}}/actions/workflows/docs.yml/badge.svg
[documentation-link]: https://github.com/{{cookiecutter.github_username}}/{{cookiecutter.project_slug}}/actions/workflows/docs.yml
[tests-badge]: {{cookiecutter.__repo_url}}/actions/workflows/tests.yml/badge.svg
[tests-link]: {{cookiecutter.__repo_url}}/actions/workflows/tests.yml
[linting-badge]: {{cookiecutter.__repo_url}}/actions/workflows/linting.yml/badge.svg
[linting-link]: {{cookiecutter.__repo_url}}/actions/workflows/linting.yml
[documentation-badge]: {{cookiecutter.__repo_url}}/actions/workflows/docs.yml/badge.svg
[documentation-link]: {{cookiecutter.__repo_url}}/actions/workflows/docs.yml
{%- if cookiecutter.license == "MIT" %}
[license-badge]: https://img.shields.io/badge/License-MIT-yellow.svg
{%- elif cookiecutter.license == "BSD-3" %}
Expand Down Expand Up @@ -68,13 +68,13 @@ development version of `{{cookiecutter.project_slug}}` using `pip` in the curren
environment run

```sh
pip install git+https://github.com/{{cookiecutter.github_username}}/{{cookiecutter.project_slug}}.git
pip install git+{{cookiecutter.__repo_url}}.git
```

Alternatively create a local clone of the repository with

```sh
git clone https://github.com/{{cookiecutter.github_username}}/{{cookiecutter.project_slug}}.git
git clone {{cookiecutter.__repo_url}}.git
```

and then install in editable mode by running
Expand Down
6 changes: 3 additions & 3 deletions {{cookiecutter.project_slug}}/mkdocs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,8 @@ site_name: "{{cookiecutter.project_name}}"
site_description: "Documentation website for {{cookiecutter.project_name}}"
site_author: "{{cookiecutter.author_given_names}} {{cookiecutter.author_family_names}}"
copyright: "Copyright © {% now 'utc', '%Y' %} {{cookiecutter.author_given_names}} {{cookiecutter.author_family_names}}"
repo_url: "https://github.com/{{cookiecutter.github_username}}/{{cookiecutter.project_slug}}/"
repo_name: "{{cookiecutter.github_username}}/{{cookiecutter.project_slug}}"
repo_url: "{{cookiecutter.__repo_url}}/"
repo_name: "{{cookiecutter.__repo_name}}"
edit_uri: edit/main/docs/

validation:
Expand Down Expand Up @@ -60,4 +60,4 @@ plugins:
extra:
social:
- icon: fontawesome/brands/github
link: "https://github.com/{{cookiecutter.github_username}}"
link: "https://github.com/{{cookiecutter.github_owner}}"
2 changes: 1 addition & 1 deletion {{cookiecutter.project_slug}}/pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -50,7 +50,7 @@ optional-dependencies = {dev = [
readme = "README.md"
requires-python = ">={{cookiecutter.min_python_version}}"
license.file = "LICENSE.md"
urls.homepage = "https://github.com/{{cookiecutter.github_username}}/{{cookiecutter.project_slug}}"
urls.homepage = "{{cookiecutter.__repo_url}}"

[tool.coverage]
report = {sort = "cover"}
Expand Down

0 comments on commit 85b0b29

Please sign in to comment.