Merge branch 'main' into refactor/extract-copier-test

Author: lwjohnst86

.pre-commit-config.yaml

@@ -25,6 +25,6 @@ repos:
   # sub-packages, which confuses pre-commit when it tries to find the latest
   # version
   - repo: https://github.com/adhtruong/mirrors-typos
-    rev: v1.35.4
+    rev: v1.35.5
     hooks:
       - id: typos

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) }}"

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.

template/.github/workflows/build-website.yml

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

template/.github/workflows/build-website.yml.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 }}"

template/CITATION.cff.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

template/LICENSE.md.jinja

@@ -11,19 +11,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"
@@ -32,7 +37,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
@@ -55,7 +60,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:

template/_publish.yml

@@ -1,3 +1,3 @@
 <!-- TODO: Set up GoatCounter -->
-<script data-goatcounter="https://{{ github_user }}-{{ package_name }}.goatcounter.com/count" async
+<script data-goatcounter="https://{{ github_user }}-{{ github_repo }}.goatcounter.com/count" async
   src="//gc.zgo.at/count.js"></script>