diff --git a/404.qmd b/404.qmd new file mode 100644 index 0000000..9a29f89 --- /dev/null +++ b/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} diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..e69de29 diff --git a/CITATION.cff b/CITATION.cff new file mode 100644 index 0000000..dd34abd --- /dev/null +++ b/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" diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..7c4d319 --- /dev/null +++ b/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. diff --git a/_metadata.yml b/_metadata.yml new file mode 100644 index 0000000..0004cf6 --- /dev/null +++ b/_metadata.yml @@ -0,0 +1,4 @@ +# Metadata for the website +gh: + org: "seedcase-project" + repo: "template-python-package" diff --git a/_quarto.yml b/_quarto.yml index 192ca97..efe8dac 100644 --- a/_quarto.yml +++ b/_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 diff --git a/docs/guide.qmd b/docs/guide.qmd new file mode 100644 index 0000000..c1c60fb --- /dev/null +++ b/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. diff --git a/docs/includes/_badges.qmd b/docs/includes/_badges.qmd new file mode 100644 index 0000000..3a186bc --- /dev/null +++ b/docs/includes/_badges.qmd @@ -0,0 +1,9 @@ + +[![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 website](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) diff --git a/docs/includes/site-counter.html b/docs/includes/site-counter.html new file mode 100644 index 0000000..b5dfe6e --- /dev/null +++ b/docs/includes/site-counter.html @@ -0,0 +1,3 @@ + + diff --git a/docs/releases.qmd b/docs/releases.qmd new file mode 100644 index 0000000..41b6f91 --- /dev/null +++ b/docs/releases.qmd @@ -0,0 +1,15 @@ +--- +title: "Releases" +--- + +Since we follow [Conventional +Commits](https://decisions.seedcase-project.org/why-conventional-commits), +we're able to automatically create a release based on the commit message +by using +[Commitizen](https://decisions.seedcase-project.org/why-semantic-release-with-commitizen). +This means that releases can happen quite often, sometimes several in +a day. It also means any individual release will not have many changes +within it. Below is a list of releases along with what was changed +within it. + +{{< include /CHANGELOG.md >}} diff --git a/index.qmd b/index.qmd index 3d0f710..baf849a 100644 --- a/index.qmd +++ b/index.qmd @@ -1,5 +1,72 @@ --- -title: "Welcome to NAME!" +title: An opinionated template for Python Packages --- -{{< include /docs/includes/_wip.qmd >}} +{{< include /docs/includes/_badges.qmd >}} + +This is a template for creating a new Python package following the +Seedcase structure. Use this template to quickly get started with a new +Python package with all the necessary files and configurations in place, +including for developing the package. + +## Features + +- Use [uv](https://decisions.seedcase-project.org/why-uv/) to manage + the Python package and for project management. +- Includes a [justfile](https://just.systems/man/en/) for managing + common tasks like building the website and running checks. +- Uses [typos](https://github.com/crate-ci/typos) to check for common + spelling mistakes. +- Code formatting and linting with + [ruff](https://decisions.seedcase-project.org/why-ruff/). +- Run checks with [pre-commit](https://pre-commit.com/) hooks to + ensure consistent formatting and style across the project. It + includes checks for credentials, typos, and file formatting. +- GitHub workflows for automatically adding Pull Requests and Issues + to a project board. +- Pull Request template for easy creation of new Pull Requests. +- Includes [GitHub Actions](https://docs.github.com/en/actions) for + continuous integration, testing, and delivery for running checks, + formatting, releasing, and building the Python package and associated + documentation. +- Pull Request template for easy creation of new Pull Requests. +- [VS Code](https://code.visualstudio.com/) settings commonly used by + contributors working in VS Code. +- Includes an [EditorConfig](https://editorconfig.org/) file to ensure + consistent formatting across different editors. +- [`CITATION.cff`](https://citation-file-format.github.io/) file for + citation information. +- Python package folder and file structure that takes advantage of + Python's packaging ecosystem. +- [`pyproject.toml`](https://peps.python.org/pep-0518/) for tracking + dependencies and project metadata. +- Uses [Quarto](https://quarto.org/) Markdown for the website content, + allowing for easy integration of code, text, and figures. +- Uses + [Commitizen](https://decisions.seedcase-project.org/why-changelog-with-commitizen) + to + [check](https://decisions.seedcase-project.org/why-lint-with-commitizen/) + commit messages and automatically create the changelog. +- Automated Git tagging and GitHub releases with + [commitizen](https://decisions.seedcase-project.org/why-semantic-release-with-commitizen/) + that are based on messages following [Conventional + Commits](https://decisions.seedcase-project.org/why-conventional-commits). +- Uses a [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/) + license for the website content. +- Uses an [MIT](https://decisions.seedcase-project.org/why-mit-license/index.html) + license for the code. +- Optionally uses the + [`seedcase-theme`](https://github.com/{{< meta gh.org >}}/seedcase-theme) + Quarto extension for a standard appearance across websites. +- Uses [Netlify](https://www.netlify.com/) for hosting the website. + +## Want to contribute? + +We would love your feedback or contributions! Head over to our [GitHub +repository](https://github.com/{{< meta gh.org >}}/{{< meta gh.repo >}}) to +share your ideas or contribute code. Your input makes us better! + +## Licensing + +This project is licensed under the [MIT +License](https://github.com/{{< meta gh.org >}}/{{< meta gh.repo >}}/blob/main/LICENSE.md).