diff --git a/.config/panache.toml b/.config/panache.toml new file mode 100644 index 0000000..a385616 --- /dev/null +++ b/.config/panache.toml @@ -0,0 +1,15 @@ +flavor = "quarto" +exclude = [".git/", ".github/", "LICENSE.md", "README.md"] + +[format] +tab-width = 2 + +[linters] +r = "jarl" +python = "ruff" +rust = "clippy" + +[formatters] +r = "air" +python = "ruff" +rust = "rustfmt" diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 70f24c2..2cd41c4 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -56,7 +56,7 @@ jobs: with: command: check - # Install uv to use git-cliff and rumdl + # Install uv to use git-cliff and panache - name: Set up uv uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0 with: diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index a95bf9f..b23d0cf 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -10,6 +10,11 @@ repos: hooks: - id: gitleaks + - repo: https://github.com/jolars/panache-pre-commit + rev: v2.51.0 + hooks: + - id: panache-format + - repo: https://github.com/pre-commit/pre-commit-hooks rev: v6.0.0 hooks: @@ -28,8 +33,3 @@ repos: hooks: - id: typos args: [--config, .config/typos.toml, --force-exclude] - - - repo: https://github.com/rvben/rumdl-pre-commit - rev: v0.2.28 - hooks: - - id: rumdl-fmt # Auto-format diff --git a/.vscode/extensions.json b/.vscode/extensions.json index fdea16c..49b5940 100644 --- a/.vscode/extensions.json +++ b/.vscode/extensions.json @@ -14,7 +14,8 @@ "tekumara.typos-vscode", "EditorConfig.EditorConfig", "samuelcolvin.jinjahtml", - "rvben.rumdl" + "rvben.rumdl", + "jolars.panache" ], "unwantedRecommendations": [] } diff --git a/.vscode/settings.json b/.vscode/settings.json index ffd3128..8241c5f 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -15,8 +15,8 @@ "perf" ], "conventional-branch.format": "{Type}/{Branch}", - "[quarto][qmd][jinja]": { - "editor.formatOnSave": false + "[quarto][qmd][md][jinja]": { + "editor.defaultFormatter": "jolars.panache" }, "files.associations": { "justfile.jinja": "plaintext", diff --git a/CHANGELOG.md b/CHANGELOG.md index b6012fd..f056e46 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1134,7 +1134,7 @@ changelog. ### ❤️ New contributors -- `@github-actions[bot]` started making automated contributions +- `@github-actions[bot]` started making automated contributions <<<<<<< HEAD - [`@martonvago`](https://github.com/martonvago) made their first contribution in @@ -1147,6 +1147,21 @@ changelog. - [`@lwjohnst86`](https://github.com/lwjohnst86) made their first contribution in [#150](https://github.com/seedcase-project/template-python-package/pull/150) + ======= -- [`@signekb`](https://github.com/signekb) made their first contribution in - [#44](https://github.com/seedcase-project/template-python-package/pull/44) +- [`@martonvago`](https://github.com/martonvago) made their first contribution + in + [#134](https://github.com/seedcase-project/template-python-package/pull/134) + +- `@pre-commit-ci[bot]` started making automated contributions + +- `@dependabot[bot]` started making automated contributions + +- [`@lwjohnst86`](https://github.com/lwjohnst86) made their first contribution + in + [#150](https://github.com/seedcase-project/template-python-package/pull/150) + +> > > > > > > 0166ab76bf12a6825d31bc8c33b9b6a23b177d52 - +> > > > > > > [`@signekb`](https://github.com/signekb) made their first +> > > > > > > contribution in +> > > > > > > [#44](https://github.com/seedcase-project/template-python-package/pull/44) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1b274a1..d1ba291 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -20,9 +20,9 @@ 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 first -[install uv](https://docs.astral.sh/uv/getting-started/installation/) and then -install justfile with uv. Once you've installed uv, install justfile by running: +It's easiest to first [install +uv](https://docs.astral.sh/uv/getting-started/installation/) and then install +justfile with uv. Once you've installed uv, install justfile by running: ```bash uv tool install rust-just @@ -48,10 +48,10 @@ 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 +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 [Cocogitto](https://decisions.seedcase-project.org/why-semantic-release-with-cocogitto/). If you don't use Conventional Commits when making a commit, we will revise the pull request title to follow that format. That's because we use squash merges @@ -71,8 +71,6 @@ as explains a bit more about them and what they are used for. configuration, pull request templates, and a [CODEOWNERS](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners) file. -- `_metadata.yml`: Quarto metadata file for the website, including information - about the project, such as the titles and GitHub names. - `_quarto.yml`: Quarto configuration file for the website, including settings for the website, such as the theme, navigation, and other options. - `_metadata.yml`: Quarto metadata file for the website, including information diff --git a/docs/guide/index.qmd b/docs/guide/index.qmd index be08873..5f8c770 100644 --- a/docs/guide/index.qmd +++ b/docs/guide/index.qmd @@ -10,6 +10,6 @@ listing: - description --- -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 +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. diff --git a/docs/guide/next-steps.qmd b/docs/guide/next-steps.qmd index a60d074..8ccfec5 100644 --- a/docs/guide/next-steps.qmd +++ b/docs/guide/next-steps.qmd @@ -5,65 +5,63 @@ description: | order: 4 --- -While most of the post-applying steps are listed in the created -`TODO.md` file within the Python package, this documents some more -details for these steps. Use this guide alongside the `TODO.md` to -complete those tasks. For example, one of the first tasks is to start -having Git track the Python package with `git init`. +While most of the post-applying steps are listed in the created `TODO.md` file +within the Python package, this documents some more details for these steps. Use +this guide alongside the `TODO.md` to complete those tasks. For example, one of +the first tasks is to start having Git track the Python package with `git init`. ## Setting up pre-commit hooks -[Pre-commit hooks](https://pre-commit.com/) are scripts that run when -committing changes to a Git repository. They are incredibly useful for -enforcing coding standards and catching errors early. The `justfile` -contains a `install-precommit` recipe that sets up the pre-commit hooks -for your Python package. Run it by opening a terminal within the Python -package directory and running the following command: +[Pre-commit hooks](https://pre-commit.com/) are scripts that run when committing +changes to a Git repository. They are incredibly useful for enforcing coding +standards and catching errors early. The `justfile` contains a +`install-precommit` recipe that sets up the pre-commit hooks for your Python +package. Run it by opening a terminal within the Python package directory and +running the following command: -```{.bash filename="Terminal"} +```bash {filename="Terminal"} just install-precommit ``` -This sets up the pre-commit hooks to run standard checks on your -repository whenever you commit files to the history. Using pre-commit -hooks as part of your workflow is even better if you connect the -continuous integration service to your repository. Go to the -[pre-commit.ci](https://pre-commit.ci/) website and follow the -instructions there to connect your repository to the service. This will -run the pre-commit hooks on every commit you push to the repository, -including pull requests, which will ensure that the code is checked for -basic issues. It will also keep the pre-commit hooks updated by creating -a pull request whenever newer versions of the hooks are available. +This sets up the pre-commit hooks to run standard checks on your repository +whenever you commit files to the history. Using pre-commit hooks as part of your +workflow is even better if you connect the continuous integration service to +your repository. Go to the [pre-commit.ci](https://pre-commit.ci/) website and +follow the instructions there to connect your repository to the service. This +will run the pre-commit hooks on every commit you push to the repository, +including pull requests, which will ensure that the code is checked for basic +issues. It will also keep the pre-commit hooks updated by creating a pull +request whenever newer versions of the hooks are available. ## Adding the Quarto theme ::: callout-warning -This step is only necessary if you are using this template for a -repository that is part of the Seedcase Project. If you are using this -template for a different project, you can skip this step. If you have -your own Quarto theme that you want to use, you can use this step as a -general guide on how to add a Quarto theme to your Python package. +This step is only necessary if you are using this template for a repository that +is part of the Seedcase Project. If you are using this template for a different +project, you can skip this step. If you have your own Quarto theme that you want +to use, you can use this step as a general guide on how to add a Quarto theme to +your Python package. ::: -For Seedcase Project repositories, we have a custom Quarto extension -that has our theme called `seedcase-theme`. The `justfile` has a recipe -called `update-quarto-theme` that adds this theme to the Python package. -Run it by opening a terminal within the Python package directory and -running the following command: +For Seedcase Project repositories, we have a custom Quarto extension that has +our theme called `seedcase-theme`. The `justfile` has a recipe called +`update-quarto-theme` that adds this theme to the Python package. Run it by +opening a terminal within the Python package directory and running the following +command: -```{.bash filename="Terminal"} +```bash {filename="Terminal"} 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. It's called `update-quarto-theme` here since you can use this -command to keep the theme updated. +This adds the `seedcase-theme` Quarto theme to the website, which provides a +consistent look and feel across all Seedcase Project websites. It's called +`update-quarto-theme` here since you can use this command to keep the theme +updated. -Then to use the theme, you need to update the `_quarto.yml` file by -adding the following lines to the `project` and `format` sections: +Then to use the theme, you need to update the `_quarto.yml` file by adding the +following lines to the `project` and `format` sections: -``` yaml {filename="_quarto.yml"} +```yaml {filename="_quarto.yml"} project: type: seedcase-theme @@ -75,109 +73,102 @@ format: seedcase-theme-html ## Setting up a GitHub repository ::: callout-warning -These series of steps are only necessary if you are using this template -for a repository that is part of the Seedcase Project. If you want a -quick way of putting your Python package on GitHub, you can use the `gh` -command line tool to upload the Python package to GitHub: +These series of steps are only necessary if you are using this template for a +repository that is part of the Seedcase Project. If you want a quick way of +putting your Python package on GitHub, you can use the `gh` command line tool to +upload the Python package to GitHub: -```{.bash filename="Terminal"} +```bash {filename="Terminal"} gh repo create ORG/REPO --source=. --public` ``` ::: -We have a custom command line tool that we developed to help manage -GitHub repositories for Seedcase Project repositories. While it's useful -for us, it isn't designed or build in a way that makes it easy for -others to use. +We have a custom command line tool that we developed to help manage GitHub +repositories for Seedcase Project repositories. While it's useful for us, it +isn't designed or build in a way that makes it easy for others to use. -For setting up a GitHub repository for the created Python package that -will be part of the Seedcase Project, you'll need to install our -internal tool [`spaid`](https://github.com/seedcase-project/spaid) and -use the following commands to run the next setup steps: +For setting up a GitHub repository for the created Python package that will be +part of the Seedcase Project, you'll need to install our internal tool +[`spaid`](https://github.com/seedcase-project/spaid) and use the following +commands to run the next setup steps: -```{.bash filename="Terminal"} +```bash {filename="Terminal"} spaid_gh_create_repo_from_local -h spaid_gh_set_repo_settings -h spaid_gh_ruleset_basic_protect_main -h spaid_gh_ruleset_require_pr -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 -some 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: +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 some +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.yml` requires the - [auto-release-token](https://github.com/apps/auto-release-token) - GitHub App, which is specific to the Seedcase Project, 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. + [auto-release-token](https://github.com/apps/auto-release-token) GitHub App, + which is specific to the Seedcase Project, 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 (another Seedcase app), along with the `ADD_TO_BOARD_TOKEN` - secret and the `ADD_TO_BOARD_APP_ID` variable of the GitHub App's ID. + [add-to-board-token](https://github.com/apps/add-to-board-token) GitHub App + (another Seedcase app), along with the `ADD_TO_BOARD_TOKEN` secret and the + `ADD_TO_BOARD_APP_ID` variable of the GitHub App's ID. ## Connecting to hosting services If you use this template to make a website hosted on -[Netlify](https://www.netlify.com/), you need to connect the GitHub -repository to Netlify. The Quarto documentation has an -[excellent guide](https://quarto.org/docs/publishing/netlify.html) on -how to do this. It includes configuring Netlify to host the website and -adding the +[Netlify](https://www.netlify.com/), you need to connect the GitHub repository +to Netlify. The Quarto documentation has an [excellent +guide](https://quarto.org/docs/publishing/netlify.html) on how to do this. It +includes configuring Netlify to host the website and adding the [`NETLIFY_AUTH_TOKEN`](https://quarto.org/docs/publishing/netlify.html#netlify-credentials) secret to the GitHub repository (or ideally at the organization level). -For hosting on [GitHub Pages](https://pages.github.com/), it's a bit -easier to set up than Netlify. The Quarto documentation again has a -[guide](https://quarto.org/docs/publishing/github-pages.html) on how to -do this. Before you can host on GitHub Pages, you need to use Quarto to -set things up for you, by running the following command: +For hosting on [GitHub Pages](https://pages.github.com/), it's a bit easier to +set up than Netlify. The Quarto documentation again has a +[guide](https://quarto.org/docs/publishing/github-pages.html) on how to do this. +Before you can host on GitHub Pages, you need to use Quarto to set things up for +you, by running the following command: -```{.bash filename="Terminal"} +```bash {filename="Terminal"} quarto publish github-pages ``` ## Auto-releasing to Zenodo ::: callout-warning -This step is only necessary if you are using this template for a -repository that is part of the Seedcase Project. If you are using this -template for a different project or organization, you can skip this -step. If you want to set up auto-releasing to Zenodo, you can use this -section to guide you to setting it up for your Python package. +This step is only necessary if you are using this template for a repository that +is part of the Seedcase Project. If you are using this template for a different +project or organization, you can skip this step. If you want to set up +auto-releasing to Zenodo, you can use this section to guide you to setting it up +for your Python package. ::: -If you create a release on GitHub, either manually or through a GitHub -workflow, you can have that release automatically create a record on -Zenodo, which is a service that allows you to archive projects and -create a DOI for it. - -GitHub and Zenodo have an integration that, when set up, will -automatically create a -[Zenodo record](https://help.zenodo.org/docs/deposit/about-records/) -from a -[GitHub release](https://docs.github.com/en/repositories/releasing-projects-on-github/about-releases). -This is useful if you want to create a DOI for your Python package, -which will allow you or others to cite it in their work as well as -provide more exposure for your Python package. Connecting GitHub to -Zenodo is very easy, check out Zenodo's -[guide](https://help.zenodo.org/docs/github/archive-software/github-upload/) -on it. +If you create a release on GitHub, either manually or through a GitHub workflow, +you can have that release automatically create a record on Zenodo, which is a +service that allows you to archive projects and create a DOI for it. + +GitHub and Zenodo have an integration that, when set up, will automatically +create a [Zenodo record](https://help.zenodo.org/docs/deposit/about-records/) +from a [GitHub +release](https://docs.github.com/en/repositories/releasing-projects-on-github/about-releases). +This is useful if you want to create a DOI for your Python package, which will +allow you or others to cite it in their work as well as provide more exposure +for your Python package. Connecting GitHub to Zenodo is very easy, check out +Zenodo's +[guide](https://help.zenodo.org/docs/github/archive-software/github-upload/) on +it. ## Setting up GoatCounter -If you want to use GoatCounter for website visitor tracking, you need to -create a GoatCounter account and set up a new site for your website. -Adding a new site is very easy. Go into the "Settings" after logging -into your account. Under "Sites", click "Add new site" and fill in the -form with your website's unique name. You can use the auto-filled name -in the `docs/includes/site-counter.html` file, which has the format of -"orgname-reponame" or modify your own. +If you want to use GoatCounter for website visitor tracking, you need to create +a GoatCounter account and set up a new site for your website. Adding a new site +is very easy. Go into the "Settings" after logging into your account. Under +"Sites", click "Add new site" and fill in the form with your website's unique +name. You can use the auto-filled name in the `includes/site-counter.html` file, +which has the format of "orgname-reponame" or modify your own. diff --git a/docs/guide/using.qmd b/docs/guide/using.qmd index 7adf9a4..636bf2c 100644 --- a/docs/guide/using.qmd +++ b/docs/guide/using.qmd @@ -6,46 +6,45 @@ description: | order: 2 --- -This guide walks through how to use this template to create a new Python -package or apply it to an existing Python package. +This guide walks through how to use this template to create a new Python package +or apply it to an existing Python package. ## 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 Python package smoothly and effectively. -First, open a terminal and run the following command: +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 Python package smoothly and effectively. First, open a +terminal and run the following command: -```{.bash filename="Terminal"} +```bash {filename="Terminal"} uvx copier copy gh:seedcase-project/template-python-package path/to/package/package-name ``` The `copy` command uses the template on GitHub (`gh:`) at the -`seedcase-project/template-python-package` location. The `path/to/` is -the location where you'd like the new Python package to be created and -`package-name` is the name you want to give for the new package's -directory and (ideally) the GitHub repository for the package. The name -should be something short and meaningful, ideally lowercase, with `-` -instead of spaces, and no special characters. +`seedcase-project/template-python-package` location. The `path/to/` is the +location where you'd like the new Python package to be created and +`package-name` is the name you want to give for the new package's directory and +(ideally) the GitHub repository for the package. The name should be something +short and meaningful, ideally lowercase, with `-` instead of spaces, and no +special characters. ## Applying 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. +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 filename="Terminal"} +```bash {filename="Terminal"} uvx copier copy gh:seedcase-project/template-python-package path/to/existing-package ``` -See the comment above in the "Creating a new Python package" section -about the naming of the existing package directory. 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 the +naming of the existing package directory. 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 existing package needs to be tracked by -Git and in a clean state (no changes have been made in the working -directory). +To use the `copy` command, the existing package needs to be tracked by Git and +in a clean state (no changes have been made in the working directory). ::: diff --git a/index.qmd b/index.qmd index 3df257f..0a71a34 100644 --- a/index.qmd +++ b/index.qmd @@ -4,74 +4,72 @@ title: "{{< meta tagline >}}" {{< 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. +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. +- 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. + 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. +- 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. +- [`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 [Quarto](https://quarto.org/) Markdown for the website content, allowing + for easy integration of code, text, and figures. - Uses [git-cliff](https://decisions.seedcase-project.org/why-changelog-with-git-cliff/) to automatically create the changelog. - Automates Git tagging and GitHub releases with [Cocogitto](https://decisions.seedcase-project.org/why-semantic-release-with-cocogitto/) - 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/) - license for the code. + 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/) license + for the code. - Optionally uses the - [`seedcase-theme`](https://github.com/seedcase-project/seedcase-theme) - Quarto extension for a standard appearance across websites. + [`seedcase-theme`](https://github.com/seedcase-project/seedcase-theme) Quarto + extension for a standard appearance across websites. - Uses [Netlify](https://www.netlify.com/) for hosting the website. -- Includes a [GoatCounter](https://www.goatcounter.com/) file for - website visitor tracking, which is privacy-friendly and does not use - cookies. That means it doesn't need a GDPR notice as no personal data - is collected. -- Uses [rumdl](https://rumdl.dev/) to format Markdown files so that they - are standardized and consistent across the project, as well as being - easier to read in raw form. -- Checks URLs with [Lychee](https://lychee.cli.rs) to ensure they aren't - broken or blocked. +- Includes a [GoatCounter](https://www.goatcounter.com/) file for website + visitor tracking, which is privacy-friendly and does not use cookies. That + means it doesn't need a GDPR notice as no personal data is collected. +- Uses [rumdl](https://rumdl.dev/) and [Panache](https://panache.bz/) to format + Markdown files so that they are standardized and consistent across the + project, as well as being easier to read in raw form. +- Checks URLs with [Lychee](https://lychee.cli.rs) to ensure they aren't broken + or blocked. ## Want to contribute? -We would love your feedback or contributions! Head over to our -[GitHub repository]({{< meta links.github >}}) to share your ideas or -contribute code. Your input makes us better! +We would love your feedback or contributions! Head over to our [GitHub +repository]({{< meta links.github >}}) to share your ideas or contribute code. +Your input makes us better! ### Contributors diff --git a/justfile b/justfile index 5c0b6ef..6485387 100644 --- a/justfile +++ b/justfile @@ -56,9 +56,11 @@ check-urls: # Format Markdown files format-md: + # Use both rumdl and panache, for different purposes uvx rumdl fmt --silent - # includes option doesn't work with Jinja files, so do manually + # `includes` option doesn't work with Jinja files, so do manually uvx rumdl fmt --silent **/*.qmd.jinja **/*.md.jinja + uvx --from panache-cli panache format . --quiet # Test template creation with specific parameters: LIST test for_seedcase="true" hosting_provider="netlify": diff --git a/template/.config/cog.toml b/template/.config/cog.toml index 37117a8..2cd8a32 100644 --- a/template/.config/cog.toml +++ b/template/.config/cog.toml @@ -5,7 +5,7 @@ branch_whitelist = ["main"] pre_bump_hooks = [ # Quiet the log output of git-cliff, it is noisy. "RUST_LOG='none' uvx git-cliff --tag {{version}}", - "uvx rumdl fmt CHANGELOG.md --silent", + "uvx --from panache-cli panache format CHANGELOG.md --quiet", "uv version {{version}}", "git commit CHANGELOG.md pyproject.toml uv.lock -m 'build: 🔖 update version to {{version}} [skip ci]'", ] diff --git a/template/.config/panache.toml b/template/.config/panache.toml new file mode 100644 index 0000000..a385616 --- /dev/null +++ b/template/.config/panache.toml @@ -0,0 +1,15 @@ +flavor = "quarto" +exclude = [".git/", ".github/", "LICENSE.md", "README.md"] + +[format] +tab-width = 2 + +[linters] +r = "jarl" +python = "ruff" +rust = "clippy" + +[formatters] +r = "air" +python = "ruff" +rust = "rustfmt" diff --git a/template/.github/workflows/release.yml b/template/.github/workflows/release.yml index df58f15..209c15a 100644 --- a/template/.github/workflows/release.yml +++ b/template/.github/workflows/release.yml @@ -60,7 +60,7 @@ jobs: with: command: check - # Install uv to use git-cliff and rumdl + # Install uv to use git-cliff and panache - name: Set up uv uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0 with: diff --git a/template/.pre-commit-config.yaml b/template/.pre-commit-config.yaml index fbfa793..c5e4590 100644 --- a/template/.pre-commit-config.yaml +++ b/template/.pre-commit-config.yaml @@ -10,6 +10,11 @@ repos: hooks: - id: gitleaks + - repo: https://github.com/jolars/panache-pre-commit + rev: v2.51.0 + hooks: + - id: panache-format + - repo: https://github.com/pre-commit/pre-commit-hooks rev: v6.0.0 hooks: @@ -28,11 +33,6 @@ repos: hooks: - id: typos - - repo: https://github.com/rvben/rumdl-pre-commit - rev: v0.1.94 - hooks: - - id: rumdl-fmt - - repo: https://github.com/astral-sh/ruff-pre-commit # Ruff version. rev: v0.15.16 diff --git a/template/.vscode/extensions.json b/template/.vscode/extensions.json index 18ec7f6..877612b 100644 --- a/template/.vscode/extensions.json +++ b/template/.vscode/extensions.json @@ -1,7 +1,7 @@ { "recommendations": [ "eamodio.gitlens", - "github.vscode-github-actions", + "GitHub.vscode-github-actions", "redhat.vscode-yaml", "donjayamanne.githistory", "felipecaputo.git-project-manager", @@ -17,7 +17,8 @@ "pshaddel.conventional-branch", "tekumara.typos-vscode", "EditorConfig.EditorConfig", - "rvben.rumdl" + "rvben.rumdl", + "jolars.panache" ], "unwantedRecommendations": [] } diff --git a/template/.vscode/settings.json b/template/.vscode/settings.json index 21c4099..46d6c2e 100644 --- a/template/.vscode/settings.json +++ b/template/.vscode/settings.json @@ -16,8 +16,9 @@ "perf" ], "conventional-branch.format": "{Type}/{Branch}", - "[quarto][qmd]": { - "editor.formatOnSave": false + "[quarto][qmd][md]": { + "editor.formatOnSave": false, + "editor.defaultFormatter": "jolars.panache" }, "[python]": { "editor.defaultFormatter": "charliermarsh.ruff" diff --git a/template/CONTRIBUTING.md.jinja b/template/CONTRIBUTING.md.jinja index fcede07..31f7211 100644 --- a/template/CONTRIBUTING.md.jinja +++ b/template/CONTRIBUTING.md.jinja @@ -83,9 +83,10 @@ commit. configuration file for type checking Python code. - `ruff.toml`: [Ruff](https://docs.astral.sh/ruff/) configuration file for linting and formatting Python code. - - `rumdl.toml`: [rumdl](https://rumdl.dev/) configuration file for - formatting Markdown files so that they are standardized and consistent - {%- if for_seedcase %} + - `rumdl.toml` and `panache.toml`: [rumdl](https://rumdl.dev) and + [Panache](https://panache.bz) configuration file for formatting Markdown + files in the project. + {% if for_seedcase -%} - `cog.toml`: [Cocogitto](https://docs.cocogitto.io) configuration file for managing versions. - `cliff.toml`: [git-cliff](https://git-cliff.org) configuration file for diff --git a/template/README.qmd b/template/README.qmd index 35ff771..f91391d 100644 --- a/template/README.qmd +++ b/template/README.qmd @@ -12,26 +12,24 @@ metadata-files: -Check out our [website]({{< meta links.site >}}) for more information, -such as the features it provides and a -[guide]({{< meta links.site >}}/docs/guide) to using the package. For a -list of changes, see our [changelog](CHANGELOG.md). +Check out our [website]({{< meta links.site >}}) for more information, such as +the features it provides and a [guide]({{< meta links.site >}}/docs/guide) to +using the package. For a list of changes, see our [changelog](CHANGELOG.md). ::: callout-tip -This Python package was generated from the -[Template Python Package](https://github.com/seedcase-project/template-python-package) -Seedcase template :tada: +This Python package was generated from the [Template Python +Package](https://github.com/seedcase-project/template-python-package) Seedcase +template :tada: ::: ## Contributing -Check out our [contributing document](CONTRIBUTING.md) for information -on how to contribute to the project, including how to set up your -development environment. +Check out our [contributing document](CONTRIBUTING.md) for information on how to +contribute to the project, including how to set up your development environment. -Please note that this project is released with a -[Contributor Code of Conduct](CODE_OF_CONDUCT.md). By participating in -this project you agree to abide by its terms. +Please note that this project is released with a [Contributor Code of +Conduct](CODE_OF_CONDUCT.md). By participating in this project you agree to +abide by its terms. ::: content-hidden ### Contributors @@ -53,6 +51,7 @@ If you use this package in your work, please cite it as follows: ```{python} #| output: asis + !uvx --quiet cffconvert --format apalike ``` diff --git a/template/TODO.md b/template/TODO.md index 26f431c..c74d04d 100644 --- a/template/TODO.md +++ b/template/TODO.md @@ -1,5 +1,5 @@ -- Review the - [template guide](https://t-squared.seedcase-project.org/docs/guide/) for more +- Review the [template + guide](https://t-squared.seedcase-project.org/docs/guide/) for more information on how to use the template and the next steps after copying the project. - Run `git init -b main` to create the project as a Git repository. diff --git a/template/docs/includes/_badges.qmd b/template/docs/includes/_badges.qmd index 9ea523a..8fabee3 100644 --- a/template/docs/includes/_badges.qmd +++ b/template/docs/includes/_badges.qmd @@ -1,15 +1,25 @@ [![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.svg)](https://github.com/copier-org/copier) -[![Python Version from PEP 621 TOML](https://img.shields.io/python/required-version-toml?tomlFilePath=https%3A%2F%2Fraw.githubusercontent.com%2F{{< meta gh.org >}}%2F{{< meta gh.repo >}}%2Frefs%2Fheads%2Fmain%2Fpyproject.toml)](https://github.com/{{< meta gh.org >}}/{{< meta gh.repo >}}/blob/main/pyproject.toml) -[![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) -[![Check package](https://github.com/{{< meta gh.org >}}/{{< meta gh.repo >}}/actions/workflows/check-package.yml/badge.svg)](https://github.com/{{< meta gh.org >}}/{{< meta gh.repo >}}/actions/workflows/check-package.yml) -[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/{{< meta gh.org >}}/{{< meta gh.repo >}}/badge?raw=true.svg)](https://scorecard.dev/viewer/?uri=github.com/{{< meta gh.org >}}/{{< meta gh.repo >}}) +[![Python Version from PEP 621 +TOML](https://img.shields.io/python/required-version-toml?tomlFilePath=https%3A%2F%2Fraw.githubusercontent.com%2F{{< meta gh.org >}}%2F{{< meta gh.repo >}}%2Frefs%2Fheads%2Fmain%2Fpyproject.toml)](https://github.com/{{< meta gh.org >}}/{{< meta gh.repo >}}/blob/main/pyproject.toml) +[![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) +[![Check +package](https://github.com/{{< meta gh.org >}}/{{< meta gh.repo >}}/actions/workflows/check-package.yml/badge.svg)](https://github.com/{{< meta gh.org >}}/{{< meta gh.repo >}}/actions/workflows/check-package.yml) +[![OpenSSF +Scorecard](https://api.scorecard.dev/projects/github.com/{{< meta gh.org >}}/{{< meta gh.repo >}}/badge?raw=true.svg)](https://scorecard.dev/viewer/?uri=github.com/{{< meta gh.org >}}/{{< meta gh.repo >}}) [![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) -[![code coverage](https://raw.githubusercontent.com/{{< meta gh.org >}}/{{< meta gh.repo >}}/coverage/coverage.svg?raw=true)](https://htmlpreview.github.io/?https://raw.githubusercontent.com/{{< meta gh.org >}}/{{< meta gh.repo >}}/coverage/index.html) -[![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) +[![code +coverage](https://raw.githubusercontent.com/{{< meta gh.org >}}/{{< meta gh.repo >}}/coverage/coverage.svg?raw=true)](https://htmlpreview.github.io/?https://raw.githubusercontent.com/{{< meta gh.org >}}/{{< meta gh.repo >}}/coverage/index.html) +[![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: WIP – Initial development is in progress, but there has not yet been a stable, usable release suitable for the public.](https://www.repostatus.org/badges/latest/wip.svg)](https://www.repostatus.org/#wip) +[![Project Status: WIP -- Initial development is in progress, but there has not +yet been a stable, usable release suitable for the +public.](https://www.repostatus.org/badges/latest/wip.svg)](https://www.repostatus.org/#wip)