docs: 📝 add website files

404.qmd

@@ -0,0 +1,11 @@
+---
+title: "You’ve entered the garden of missing pages"
+---
+
+Let's get you back to greener grounds.
+
+👉 Go to [homepage](/index.qmd).
+
+![](/_extensions/seedcase-project/seedcase-theme/images/404.svg){fig-alt="An illustration of the number 404 surrounded by trees and mountains"}
+
+## Illustration by [Storyset](https://storyset.com/web) {.appendix}

CITATION.cff

@@ -0,0 +1,31 @@
+title: "Template Python Package: An opinionated setup for making Python packages"
+abstract: "A template for making a Git repository that follows strongly opinionated practices for building and managing Python packages."
+authors:
+  - family-names: Johnston
+    given-names: Luke William
+    orcid: "https://orcid.org/0000-0003-4169-2616"
+    affiliation: "Steno Diabetes Center Aarhus"
+  - family-names: Brødbæk
+    given-names: Signe Kirk
+    affiliation: "Steno Diabetes Center Aarhus"
+    orcid: "https://orcid.org/0009-0000-2208-7088"
+  - family-names: Beicher
+    given-names: Kristiane
+    affiliation: "Steno Diabetes Center Aarhus"
+    orcid: "https://orcid.org/0000-0001-7556-9566"
+  - family-names: Vago
+    given-names: Marton
+    affiliation: "Steno Diabetes Center Aarhus"
+cff-version: 1.2.0
+# doi:
+# date:
+keywords:
+  - "copier template"
+  - "template"
+  - "template repository"
+  - "template project"
+  - "template python package"
+license: MIT
+message: "If you use this software, please cite it using these metadata."
+repository-code: "https://github.com/seedcase-project/template-python-package"
+url: "https://template-python-package.seedcase-project.org"

CONTRIBUTING.md

@@ -0,0 +1,62 @@
+# Contributing
+
+## Issues and bugs :bug:
+
+The easiest way to contribute is to report issues or bugs that you might
+find while using `template-python-package`. You can do this by creating a
+[new](https://github.com/seedcase-project/template-python-package/issues/new/choose)
+issue on our GitHub repository.
+
+## Adding or modifying content :pencil2:
+
+If you would like to contribute content, please check out our
+[guidebook](https://guidebook.seedcase-project.org/) for more specific
+details on how we work and develop. It is a regularly evolving document,
+so is at various states of completion.
+
+To contribute to `template-python-package`, you first need to install
+[uv](https://docs.astral.sh/uv/) and
+[justfile](https://just.systems/man/en/packages.html). We use uv and
+justfile to manage our project, such as to run checks and test the
+template. Both the uv and justfile websites have a more detailed guide
+on using uv, but below are some simple instructions to get you started.
+
+It's easiest to install uv and justfile using
+[pipx](https://pypa.github.io/pipx/), so install that first. Then,
+install uv and justfile by running:
+
+``` bash
+pipx install uv rust-just
+```
+
+We keep all our development workflows in the `justfile`, so you can
+explore it to see what commands are available. To see a list of commands
+available, run:
+
+``` bash
+just
+```
+
+As you contribute, make sure your changes will pass our tests by opening
+a terminal so that the working directory is the root of this project
+(`template-python-package/`) and running:
+
+``` bash
+just run-all
+```
+
+When testing the template, copier can only use content kept in the Git
+history. Meaning that if you make changes to the template and try to
+test it, it won't be able to test those changes. You have to commit the
+changes first in order for copier to use them.
+
+When committing changes, please try to follow [Conventional
+Commits](https://decisions.seedcase-project.org/why-conventional-commits)
+as Git messages. Using this convention allows us to be able to
+automatically create a release based on the commit message by using
+[Commitizen](https://decisions.seedcase-project.org/why-semantic-release-with-commitizen).
+If you don't use Conventional Commits when making a commit, we will
+revise the pull request title to follow that format, as we use [squash
+merges](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/squashing-commits/about-squash-merges)
+when merging pull requests, so all other commits in the pull request
+will be squashed into one commit.

_metadata.yml

@@ -0,0 +1,4 @@
+# Metadata for the website
+gh:
+  org: "seedcase-project"
+  repo: "template-python-package"

_quarto.yml

@@ -1,51 +1,52 @@
 project:
   type: seedcase-theme
-  # Delete auto-generated files from `quartodoc`
-  post-render: rm docs/reference/*.qmd
   render:
-    - "docs/*"
+    # Don't render anything in the template directory.
+    - "!template/"
+    - "docs/"
     - "index.qmd"
+    - "404.qmd"
+    - "CONTRIBUTING.md"
 
 website:
-  title: "Seedcase NAME"
-  site-url: "https://NAME.seedcase-project.org/"
-  repo-url: "https://github.com/seedcase-project/REPO"
+  title: "Template Python Package"
+  site-url: "https://template-python-package.seedcase-project.org"
+  repo-url: "https://github.com/seedcase-project/template-python-package"
   page-navigation: true
   navbar:
+    logo: _extensions/seedcase-project/seedcase-theme/logos/seedcase-logo.svg
+    logo-alt: "Seedcase Project logo: Main page"
     pinned: true
-    title: false
-    logo: "_extensions/seedcase-project/seedcase-theme/logos/navbar-logo-seedcase-NAME.svg"
-    logo-alt: "Seedcase NAME logo: Main page"
     left:
+      - text: "Overview"
+        menu:
+          - text: "Welcome"
+            href: index.qmd
+          - text: "Releases"
+            href: docs/releases.qmd
+          - text: "Contributing"
+            href: CONTRIBUTING.md
       - text: "Guide"
-        href: docs/guide/index.qmd
-      - text: "Design"
-        href: docs/design/index.qmd
+        href: docs/guide.qmd
     tools:
       - icon: github
-        href: "https://github.com/seedcase-project/REPO"
+        href: "https://github.com/seedcase-project/template-python-package"
         aria-label: "GitHub icon: Source code"
       - icon: house
         href: https://seedcase-project.org
         aria-label: "House icon: Seedcase Project home page"
-  sidebar:
-    - id: design
-      pinned: true
-      style: "floating"
-      contents:
-        - text: "Design"
-          href: docs/design/index.qmd
-    - id: guide
-      contents:
-        - section: "Guide"
-          href: docs/guide/index.qmd
 
-# format:
-#   seedcase-theme-html:
-    # include-before-body:
-      # - "includes/site-counter.html"
+format:
+  seedcase-theme-html:
+    theme:
+      - brand
+    include-before-body:
+    - "docs/includes/site-counter.html"
 
 editor:
   markdown:
     wrap: 72
     canonical: true
+
+execute:
+  echo: false

docs/guide.qmd

@@ -0,0 +1,177 @@
+---
+title: "Guide"
+---
+
+This guide gives an overview of how to use this template for creating a
+new Python package. It includes instructions for using the template and
+post-creation tasks.
+
+## Installing
+
+In order to use this template, you need to install a few programs:
+
+-   [Python](https://www.python.org/): Required by the template tool
+    itself (copier) and for installing and using many of the tools in
+    this template.
+-   [Git](https://git-scm.com/): For version control and setting up Git
+    to track the newly created package.
+-   [copier](https://copier.readthedocs.io/en/stable/#quick-start): A
+    template tool for making new projects in a standardised and
+    structured way.
+-   [uv](https://docs.astral.sh/uv/): A tool for managing Python
+    environments and running commands. Some post-copy steps of this
+    template use uv.
+-   [just](https://just.systems/man/en/): A build management tool that
+    helps with running common build and check tasks.
+
+You will need to install Python and Git yourself, but the other tools
+can be installed using
+[`pipx`](https://pipxproject.github.io/pipx/)---which we strongly
+recommend---with the following command:
+
+``` bash
+pipx install copier uv rust-just
+```
+
+## Creating a new Python package
+
+You can use this template to create a new Python package with a standard
+set of files and folders, as well as all the features and configurations
+to make it easier to build your package more smoothly and effectively.
+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 .
+```
+
+::: 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
+[`copier.yml`](https://github.com/seedcase-project/template-python-package/blob/main/copier.yaml)
+file, under the `_tasks` key to see what commands will be run after
+copying the template, so you can know and trust what the commands are
+doing. Unfortunately, this template can't be used without the `--trust`
+option.
+:::
+
+## Applying the template to an existing Python package
+
+If you want to use this template on an existing Python package, you can
+use the `copy` command of `copier` just like above to apply the template
+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 .
+```
+
+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
+and in a clean state (no changes).
+:::
+
+## Applying the latest template changes
+
+There are two ways to update an existing Python package with the latest
+changes from the template: `update` and `recopy`.
+
+Use `update` to apply template updates to your project without
+overwriting local changes. `update` will compare the version of the
+template you used when you first copied the template with the current
+version of the template, and then apply the changes that are different.
+This also means it won't overwrite any changes you made to files in your
+current Python package, for example, if you deleted a file that was in
+the template, it won't be copied back.
+
+Use `recopy` if you want to reapply the template from scratch, which
+will overwrite any changes you made to the files that were copied from
+the template. This is useful if you want to reset the Python package to
+the state of the template. For example, if you deleted a file but want
+it back from the template or are simply curious to see if there are any
+new changes that you might want to use.
+
+In both cases, the commands are very similar and also use many of the
+same options as the `copy` command. If you want to use the same answers
+as given when you first copied the template, you can use the
+`--defaults` option. Then it will only prompt you for the questions that
+have changed since the last time you copied the template.
+
+``` bash
+uvx copier update --trust --defaults
+# Or
+uvx copier recopy --trust --defaults
+```
+
+As with the `copy` command, the Python package needs to be tracked by
+Git and must be in a clean state (no changes) for the `update` and
+`recopy` commands to work.
+
+## Post-creation setup
+
+These steps are mainly for us in the Seedcase Project to set up the
+repository with the settings we use, but you can follow them if you want
+to set up your Python package in a similar way. They are also included
+in a message after you've copied the template.
+
+After copying the template, while in the directory of the new Python
+package, run the following:
+
+``` bash
+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:
+
+``` bash
+just update-quarto-theme
+```
+
+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.
+
+Next, install [`spaid`](https://github.com/seedcase-project/spaid) and
+use the following commands to run the next setup steps:
+
+``` bash
+spaid_gh_create_repo_from_local -h
+spaid_gh_set_repo_settings -h
+spaid_gh_ruleset_basic_protect_main -h
+```
+
+Some configuration is needed after copying this template to a new
+repository, including configuration external to the repository. Some
+GitHub workflows require installing GitHub Apps, for greater security
+purposes and easier administration when managing multiple repositories.
+The [security
+section](https://guidebook.seedcase-project.org/operations/security#using-github-apps-to-generate-tokens)
+in our [Guidebook](https://guidebook.seedcase-project.org/) provides
+instructions on how to set up GitHub Apps, secrets, and variables.
+Ideally the secrets and variables should be set up in the organization
+settings. The specific workflows in this template that require this
+additional setup are:
+
+-   The workflow `.github/workflows/release-package.yml` requires the
+    [auto-release-token](https://github.com/apps/auto-release-token)
+    GitHub App as well as a creating a GitHub secret called
+    `UPDATE_VERSION_TOKEN` and a variable called `UPDATE_VERSION_APP_ID`
+    that has the App ID.
+-   The workflow `.github/workflows/add-to-project.yml` requires the
+    [add-to-board-token](https://github.com/apps/add-to-board-token)
+    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.

docs/includes/_badges.qmd

@@ -0,0 +1,9 @@
+<!-- [![DOI]()]() -->
+[![Copier](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/copier-org/copier/master/img/badge/badge-grayscale-inverted-border-teal.json?raw=true)](https://github.com/copier-org/copier)
+[![GitHub License](https://img.shields.io/github/license/{{< meta gh.org >}}/{{< meta gh.repo >}}.svg)](https://github.com/{{< meta gh.org >}}/{{< meta gh.repo >}}/blob/main/LICENSE.md)
+[![GitHub Release](https://img.shields.io/github/v/release/{{< meta gh.org >}}/{{< meta gh.repo >}}.svg)](https://github.com/{{< meta gh.org >}}/{{< meta gh.repo >}}/releases/latest)
+[![Build documentation](https://github.com/{{< meta gh.org >}}/{{< meta gh.repo >}}/actions/workflows/build-website.yml/badge.svg)](https://github.com/{{< meta gh.org >}}/{{< meta gh.repo >}}/actions/workflows/build-website.yml)
+[![CodeQL](https://github.com/{{< meta gh.org >}}/{{< meta gh.repo >}}/actions/workflows/github-code-scanning/codeql/badge.svg?branch=main)](https://github.com/{{< meta gh.org >}}/{{< meta gh.repo >}}/actions/workflows/github-code-scanning/codeql)
+[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/{{< meta gh.org >}}/{{< meta gh.repo >}}/main.svg)](https://results.pre-commit.ci/latest/github/{{< meta gh.org >}}/{{< meta gh.repo >}}/main)
+[![lifecycle](https://lifecycle.r-lib.org/articles/figures/lifecycle-experimental.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental)
+[![Project Status: Active – The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)

docs/includes/site-counter.html

@@ -0,0 +1,3 @@
+<!-- TODO: Set up GoatCounter -->
+<script data-goatcounter="https://seedcase-template-python-package.goatcounter.com/count" async
+  src="//gc.zgo.at/count.js"></script>