diff --git a/copier.yaml b/copier.yaml index 7bcd79b..ebbd734 100644 --- a/copier.yaml +++ b/copier.yaml @@ -9,23 +9,31 @@ _tasks: # Message to show after generating or regenerating the project successfully _message_after_copy: | - Your project "{{ package_name }}" has been created successfully! + Your project "{{ github_repo }}" has been created successfully! - Next steps: + See the [guide](https://template-python-package.seedcase-project.org/docs/guide) for more detail + on the next steps. Briefly: 1. Change directory to the project root: - $ cd {{ _copier_conf.dst_path }} + ``` bash + cd {{ _copier_conf.dst_path | realpath }} + ``` - 2. Install the pre-commit hooks: + 2. Install the pre-commit hooks, add (called "update" here) the Quarto extension, + and build the README: - $ just install-precommit + ``` bash + just install-precommit update-quarto-theme build-readme + ``` - 3. Install [`spaid`](https://github.com/seedcase-project/spaid) and run these commands to upload and configure your project on GitHub: + 3. Install [`spaid`](https://github.com/seedcase-project/spaid) and run these setup steps: - $ spaid_gh_create_repo_from_local -h - $ spaid_gh_set_repo_settings -h - $ spaid_gh_ruleset_basic_protect_main -h + ``` bash + spaid_gh_create_repo_from_local -h + spaid_gh_set_repo_settings -h + spaid_gh_ruleset_basic_protect_main -h + ``` 4. Configure GitHub following this [guide](https://guidebook.seedcase-project.org/operations/security#using-github-apps-to-generate-tokens): @@ -37,46 +45,37 @@ _message_after_copy: | 5. List and complete all TODO items in the repository: - $ just list-todos + ``` bash + just list-todos + ``` # Questions: -package_github_repo: - type: str - help: "What is or will be the GitHub repository spec for the project?" - placeholder: "user/repo" - validator: | - {% if package_github_repo and not (package_github_repo | regex_search('^[\w.-]+\/[\w.-]+$')) %} - Must be in the format `user/repo` and contain only alphanumeric characters and `_`, `-`, or `.`. - {% endif %} +is_seedcase_project: + type: bool + help: "Is this package part of the Seedcase Project?" + default: true -github_user: +github_repo: type: str - default: "{{ package_github_repo.split('/')[0] if package_github_repo else '' }}" + default: "{{ _copier_conf.dst_path | realpath | basename }}" when: false -package_name: +github_user: type: str - help: "What is the name of the package?" - default: "{{ _copier_conf.dst_path | basename }}" - validator: | - {% if package_name and not (package_name | regex_search('^[\w.-]+$')) %} - Must contain only alphanumeric characters and `_`, `-`, or `.`. - {% endif %} + help: "What is the name of the GitHub user or organisation where the repository will be or is stored?" + default: "{{ 'seedcase-project' if is_seedcase_project else '' }}" -package_name_snake_case: +hosting_provider: type: str - default: "{{package_name | replace('-', '_') | replace('.', '_')}}" - when: false - -is_seedcase_project: - type: bool - help: "Is this package part of the Seedcase Project?" - default: "{{ github_user == 'seedcase-project' }}" + help: "What hosting provider will you use for the documentation website?" + choices: + - netlify + - gh-pages homepage: type: str help: "What is the homepage of your project?" - default: "{{ 'https://%s.seedcase-project.org' % package_name if is_seedcase_project else '' }}" + default: "{{ 'https://%s.seedcase-project.org' % github_repo if is_seedcase_project else '' }}" author_given_name: type: str @@ -103,6 +102,16 @@ github_board_number: The board number must be an integer. {% endif %} +github_repo_snake_case: + type: str + default: "{{github_repo | replace('-', '_') | replace('.', '_')}}" + when: false + +github_repo_spec: + type: str + default: "{{ github_user }}/{{ github_repo }}" + when: false + copyright_year: type: str default: "{{ copyright_year | default('%Y' | strftime) }}" diff --git a/docs/guide.qmd b/docs/guide.qmd index 57c42a3..ac89e29 100644 --- a/docs/guide.qmd +++ b/docs/guide.qmd @@ -42,10 +42,15 @@ First, open a Terminal and move into the directory where you want to create the new Python package. Then run the following command: ``` bash -# Copy into the current directory, which is the "." -uvx copier copy --trust gh:seedcase-project/template-python-package . +uvx copier copy --trust gh:seedcase-project/template-python-package new-package ``` +Here, `new-package` is the name of the new folder you will create from +the template. The template assumes that the name of your new folder will +also be the name of the GitHub repository for the Python package. So the +new folder name should be a short, lowercase name without spaces or +special characters. + ::: callout-caution This template runs some post-copy commands using your terminal. In order to run them, you need to use the `--trust` option. Review the @@ -64,12 +69,13 @@ to the existing package. This will add all the template's files and configurations to the existing package. ``` bash -uvx copier copy --trust gh:seedcase-project/template-python-package . +uvx copier copy --trust gh:seedcase-project/template-python-package new-package ``` -It will go through a series of prompts, as in the case of creating a new -Python package, including asking if you want to overwrite existing -files. +See the comment above in the "Creating a new Python package" section +about naming the new folder. It will go through a series of prompts, as +in the case of creating a new Python package, including asking if you +want to overwrite existing files. ::: callout-note To use the `copy` command, the Python package needs to be tracked by Git @@ -129,8 +135,8 @@ just install-precommit This sets up the pre-commit hooks to run standard checks on your repository whenever you commit files to the history. -If you are using the template to create a Python package for the Seedcase -Project, run: +If you are using the template to create a Python package for the +Seedcase Project, run: ``` bash just update-quarto-theme @@ -140,9 +146,9 @@ Then set `seedcase-theme` as your project `type` in `_quarto.yml`. This adds the `seedcase-theme` Quarto theme to the website, which provides a consistent look and feel across all Seedcase Project -websites, including for Python package websites. -It's called `update-quarto-theme` here since you can use this -command to keep the theme updated. +websites, including for Python package websites. It's called +`update-quarto-theme` here since you can use this command to keep the +theme updated. Next, install [`spaid`](https://github.com/seedcase-project/spaid) and use the following commands to run the next setup steps: @@ -175,5 +181,5 @@ additional setup are: GitHub App, along with the `ADD_TO_BOARD_TOKEN` secret and the `ADD_TO_BOARD_APP_ID` variable of the GitHub App's ID. -If you use Netlify, you will also need to add a `NETLIFY_AUTH_TOKEN` secret -of your Netlify Token. +If you use Netlify, you will also need to add a `NETLIFY_AUTH_TOKEN` +secret of your Netlify Token. diff --git a/justfile b/justfile index fffcfcf..8105cae 100644 --- a/justfile +++ b/justfile @@ -3,7 +3,7 @@ @_checks: check-spelling check-commits # Test Seedcase and non-Seedcase projects -@_tests: (test "true") (test "false") +@_tests: (test "true" "netlify") (test "false" "netlify") (test "true" "gh-pages") (test "false" "gh-pages") @_builds: build-contributors build-website build-readme # Run all build-related recipes in the justfile @@ -46,60 +46,9 @@ check-commits: check-spelling: uvx typos -# Test and check that a Python package can be created from the template -test is_seedcase_project: - #!/bin/zsh - test_name="test-python-package" - test_dir="$(pwd)/_temp/{{ is_seedcase_project }}/$test_name" - template_dir="$(pwd)" - commit=$(git rev-parse HEAD) - rm -rf $test_dir - # vcs-ref means the current commit/head, not a tag. - uvx copier copy $template_dir $test_dir \ - --vcs-ref=$commit \ - --defaults \ - --trust \ - --data package_github_repo="first-last/repo" \ - --data is_seedcase_project={{ is_seedcase_project }} \ - --data author_given_name="First" \ - --data author_family_name="Last" \ - --data author_email="first.last@example.com" \ - --data review_team="@first-last/developers" \ - --data github_board_number=22 - # Run checks in the generated test Python package - cd $test_dir - git add . - git commit -m "test: initial copy" - just check-python check-spelling - # TODO: Find some way to test the `update` command - # Check that recopy works - echo "Testing recopy command -----------" - rm .cz.toml - git add . - git commit -m "test: preparing to recopy from the template" - uvx copier recopy \ - --vcs-ref=$commit \ - --defaults \ - --overwrite \ - --trust - # Check that copying onto an existing Python package works - echo "Using the template in an existing package command -----------" - rm .cz.toml .copier-answers.yml LICENSE.md - git add . - git commit -m "test: preparing to copy onto an existing package" - uvx copier copy \ - $template_dir $test_dir \ - --vcs-ref=$commit \ - --defaults \ - --trust \ - --overwrite \ - --data package_github_repo="first-last/repo" \ - --data is_seedcase_project={{ is_seedcase_project }} \ - --data author_given_name="First" \ - --data author_family_name="Last" \ - --data author_email="first.last@example.com" \ - --data review_team="@first-last/developers" \ - --data github_board_number=22 +# Test that a Python package can be created from the template, with parameters for: `is_seedcase_project` (true or false) and `hosting_provider` (either "gh-pages" or "netlify") +test is_seedcase_project="true" hosting_provider="netlify": + sh ./test-template.sh {{ is_seedcase_project }} {{ hosting_provider }} # Clean up any leftover and temporary build files cleanup: diff --git a/template/.github/workflows/build-website.yml b/template/.github/workflows/build-website.yml deleted file mode 100644 index b24f3c4..0000000 --- a/template/.github/workflows/build-website.yml +++ /dev/null @@ -1,17 +0,0 @@ -name: Build website - -on: - push: - branches: - - main - -# Limit token permissions for security -permissions: read-all - -jobs: - build-website: - uses: seedcase-project/.github/.github/workflows/reusable-build-docs-with-python.yml@main - secrets: - netlify-token: ${{ secrets.NETLIFY_AUTH_TOKEN }} - # This is to allow using `gh` CLI - github-token: ${{ secrets.GITHUB_TOKEN }} diff --git a/template/.github/workflows/build-website.yml.jinja b/template/.github/workflows/build-website.yml.jinja new file mode 100644 index 0000000..4b5543e --- /dev/null +++ b/template/.github/workflows/build-website.yml.jinja @@ -0,0 +1,26 @@ +name: Build website + +on: + push: + branches: + - main + +# Limit token permissions for security +permissions: read-all + +jobs: + build-website: + uses: seedcase-project/.github/.github/workflows/reusable-build-docs-with-python.yml@main + {%- if hosting_provider == 'gh-pages' %} + with: + hosting-provider: gh-pages + permissions: + contents: write + pages: write + {%- endif %} + secrets: + {% if hosting_provider == 'gh-pages' -%} + github-token: {{ '${{ secrets.GITHUB_TOKEN }}' }} + {%- elif hosting_provider == 'netlify' -%} + netlify-token: {{ '${{ secrets.NETLIFY_AUTH_TOKEN }}' }} + {%- endif %} diff --git a/template/CITATION.cff.jinja b/template/CITATION.cff.jinja index c03cb5b..0293166 100644 --- a/template/CITATION.cff.jinja +++ b/template/CITATION.cff.jinja @@ -20,5 +20,5 @@ keywords: - "" license: MIT message: "If you use this Python package, please cite it using these metadata." -repository-code: "https://github.com/{{ package_github_repo }}" +repository-code: "https://github.com/{{ github_repo_spec }}" url: "{{ homepage }}" diff --git a/template/LICENSE.md.jinja b/template/LICENSE.md.jinja index 8b1ba0a..898f71b 100644 --- a/template/LICENSE.md.jinja +++ b/template/LICENSE.md.jinja @@ -1,6 +1,6 @@ # MIT License -Copyright (c) {{ copyright_year }} {{ package_name }} authors +Copyright (c) {{ copyright_year }} {{ github_repo }} authors Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/template/README.md.jinja b/template/README.md.jinja index ba17175..cf2afa7 100644 --- a/template/README.md.jinja +++ b/template/README.md.jinja @@ -1,3 +1,3 @@ -# {{ package_name }} +# {{ github_repo }} diff --git a/template/README.qmd.jinja b/template/README.qmd.jinja index 117f38b..8a33baf 100644 --- a/template/README.qmd.jinja +++ b/template/README.qmd.jinja @@ -1,3 +1,3 @@ -# {{ package_name }} +# {{ github_repo }} diff --git a/template/_publish.yml b/template/_publish.yml deleted file mode 100644 index 972233d..0000000 --- a/template/_publish.yml +++ /dev/null @@ -1,5 +0,0 @@ -- source: project - netlify: - # TODO: Include Netlify details - - id: "" - url: "" diff --git a/template/_quarto.yml.jinja b/template/_quarto.yml.jinja index cf7c3ab..07dbb8d 100644 --- a/template/_quarto.yml.jinja +++ b/template/_quarto.yml.jinja @@ -9,19 +9,24 @@ project: website: # TODO: Fill in the title of the website. title: "" + {% if hosting_provider == "gh-pages" -%} + site-url: "https://{{ github_user }}.github.io/{{ github_repo }}/" + {%- elif hosting_provider == "netlify" -%} + # TODO: Set the Netlify custom domain URL site-url: "{{ homepage }}" - repo-url: "https://github.com/{{ package_github_repo }}" + {%- endif %} + repo-url: "https://github.com/{{ github_repo_spec }}" page-navigation: true navbar: pinned: true title: false {%- if is_seedcase_project %} - logo: "_extensions/seedcase-project/seedcase-theme/logos/navbar-logo-{{ package_name }}.svg" - logo-alt: "{{ package_name }} logo: Main page" + logo: "_extensions/seedcase-project/seedcase-theme/logos/navbar-logo-{{ github_repo }}.svg" + logo-alt: "{{ github_repo }} logo: Main page" {%- else %} # TODO: add logo logo: "" - logo-alt: "{{ package_name }} logo: Main page" + logo-alt: "{{ github_repo }} logo: Main page" {%- endif %} left: - text: "Guide" @@ -30,7 +35,7 @@ website: href: docs/design/index.qmd tools: - icon: github - href: "https://github.com/{{ package_github_repo }}" + href: "https://github.com/{{ github_repo_spec }}" aria-label: "GitHub icon: Source code" {% if is_seedcase_project -%} - icon: house @@ -53,7 +58,7 @@ quartodoc: sidebar: "docs/reference/_sidebar.yml" style: "pkgdown" dir: "docs/reference" - package: "{{ package_name_snake_case }}" + package: "{{ github_repo_snake_case }}" parser: google dynamic: true renderer: diff --git a/template/docs/site-counter.html.jinja b/template/docs/site-counter.html.jinja index b92291e..acb5f7b 100644 --- a/template/docs/site-counter.html.jinja +++ b/template/docs/site-counter.html.jinja @@ -1,3 +1,3 @@ - diff --git a/template/justfile.jinja b/template/justfile.jinja index ab72553..9c06085 100644 --- a/template/justfile.jinja +++ b/template/justfile.jinja @@ -111,7 +111,7 @@ build-readme: # Generate a Quarto include file with the contributors build-contributors: - sh ./tools/get-contributors.sh {{ package_github_repo }} + sh ./tools/get-contributors.sh {{ github_repo_spec }} # Check for and apply updates from the template update-from-template: diff --git a/template/pyproject.toml.jinja b/template/pyproject.toml.jinja index a12e4c8..d56d951 100644 --- a/template/pyproject.toml.jinja +++ b/template/pyproject.toml.jinja @@ -1,5 +1,5 @@ [project] -name = "{{ package_name }}" +name = "{{ github_repo }}" version = "0.1.0" # TODO: Add a description of the package. description = "" @@ -19,11 +19,9 @@ dependencies = [] [project.urls] homepage = "{{ homepage }}" -{%- if package_github_repo %} -repository = "https://github.com/{{ package_github_repo }}" -changelog = "https://github.com/{{ package_github_repo }}/blob/main/CHANGELOG.md" -issues = "https://github.com/{{ package_github_repo }}/issues" -{% endif %} +repository = "https://github.com/{{ github_repo_spec }}" +changelog = "https://github.com/{{ github_repo_spec }}/blob/main/CHANGELOG.md" +issues = "https://github.com/{{ github_repo_spec }}/issues" [build-system] requires = ["hatchling"] diff --git a/template/src/{{package_name_snake_case}}/__init__.py b/template/src/{{github_repo_snake_case}}/__init__.py similarity index 100% rename from template/src/{{package_name_snake_case}}/__init__.py rename to template/src/{{github_repo_snake_case}}/__init__.py diff --git a/template/src/{{package_name_snake_case}}/py.typed b/template/src/{{github_repo_snake_case}}/py.typed similarity index 100% rename from template/src/{{package_name_snake_case}}/py.typed rename to template/src/{{github_repo_snake_case}}/py.typed diff --git "a/template/{% if hosting_provider == \"netlify\" %}_publish.yml{% endif %}.jinja" "b/template/{% if hosting_provider == \"netlify\" %}_publish.yml{% endif %}.jinja" new file mode 100644 index 0000000..1b8bb0b --- /dev/null +++ "b/template/{% if hosting_provider == \"netlify\" %}_publish.yml{% endif %}.jinja" @@ -0,0 +1,5 @@ +- source: project + netlify: + # TODO: Include correct ID and URL + - id: "" + url: "https://{{ github_user }}-{{ github_repo }}.netlify.app" diff --git a/test-template.sh b/test-template.sh new file mode 100644 index 0000000..33f9ad2 --- /dev/null +++ b/test-template.sh @@ -0,0 +1,82 @@ +#!/usr/bin/env bash + +# Needs two arguments: +# +# 1. is_seedcase_project: true or false +# 2. hosting_provider: e.g., "github", "gitlab", etc. + +# Argument naming ----- +is_seedcase_project="${1}" +hosting_provider="${2}" + +if [ -z "$is_seedcase_project" ] || [ -z "$hosting_provider" ]; then + echo "Usage: sh $0 " + echo "Example: sh $0 true netlify" + exit 1 +fi + +# Set up variables and functions for the test ----- +test_name="test-package-$hosting_provider" +test_dir="$(pwd)/_temp/$is_seedcase_project/$test_name" +template_dir="$(pwd)" +# Use the latest commit for the template +commit=$(git rev-parse HEAD) + +# Needs three arguments: +# +# 1. Template directory +# 2. Destination directory +# 3. VCS ref (commit, branch, tag, etc.) +copy () { + # vcs-ref means the current commit/head, not a tag. + uvx copier copy $1 $2 \ + --vcs-ref=$3 \ + --defaults \ + --data is_seedcase_project=$is_seedcase_project \ + --data github_user="first-last" \ + --data hosting_provider=$hosting_provider \ + --data author_given_name="First" \ + --data author_family_name="Last" \ + --data author_email="first.last@example.com" \ + --data review_team="@first-last/developers" \ + --data github_board_number=22 \ + --overwrite \ + --skip-tasks \ + --trust +} + +# Pre-test setup ----- +# Remove the leftover directory from previous runs +rm -rf $test_dir +mkdir -p $test_dir + +# Check initial creation ----- +# TODO: Find some way to test the `update` command +# Any step that fails will exit the script with an error and not continue +echo "Testing copy for new projects when: 'is_seedcase_project'='$is_seedcase_project', 'hosting_provider'='$hosting_provider' -----------" +( + cd $test_dir && + copy $template_dir $test_dir $commit && + git init -b main && + git add . && + git commit --quiet -m "test: initial copy" && + # Check that recopy works ----- + echo "Testing recopy when: 'is_seedcase_project'='$$is_seedcase_project', 'hosting_provider'='$hosting_provider' -----------" && + rm .cz.toml && + git add . && + git commit --quiet -m "test: preparing to recopy from the template" && + uvx copier recopy \ + --vcs-ref=$commit \ + --defaults \ + --overwrite \ + --skip-tasks \ + --trust && + # Check that copying onto an existing package works ----- + echo "Testing copy in existing projects when: 'is_seedcase_project'='$is_seedcase_project', 'hosting_provider'='$hosting_provider' -----------" && + rm .cz.toml .copier-answers.yml && + git add . && + git commit --quiet -m "test: preparing to copy onto an existing package" && + copy $template_dir $test_dir $commit #&& + # Checks and builds ----- + # just run-all +)