Python package template

A python package template that contains everything you need to:

• create
• configure
• test
• document
• deploy

root/
├── package_name/             - Main package directory
│   ├── __init__.py
│   └── main.py/
├── tests/                    - Unit tests
│   ├── __init__.py
│   └── test_main.py
├── docs/                     - Documentation
│   ├── README.qmd                - Quarto document that generates README.md
│   ├── index.md                  - Main page
│   ├── contributing.md           - A contributing guide
│   ├── examples.md               - Usage examples
│   ├── stylesheets/              - CSS for the documentation
│   └── reference/                - API reference of the package
├── .github/workflows/        - CI/CD
│   ├── doc.yaml                  - Deploy website
│   ├── lint.yaml                 - Check code with ruff
│   ├── type.yaml                 - Check static typing with ty
│   ├── tests.yaml                - Run unit tests
│   └── pypi.yaml                 - New PyPI release
├── scripts/                  - Miscellaneous
│   └── release.sh                - Trigger PyPI release
├── pyproject.toml            - Configuration, metadata, dependencies
├── README.md                 - Project overview, generated by README.qmd
├── Makefile                  - Common commands needed when developing
├── LICENSE                   - License file
├── .gitignore                - Git ignore rules
├── .pre-commit-config.yaml   - Pre commit hooks
└── mkdocs.yaml               - Documentation website configuration

How to use this template

Create a new repo

• Click on Use this template and Create a new repository
• Clone your repo

git clone https://github.com/your_name/package_name.git

Replace with your package info

• Replace all your_name with your GitHub username or organization
• Replace all package_name with your actual package
• Replace info in pyproject.toml
• Change the LICENSE file to your actual license (optional)

Install dependencies

uv sync --all-groups
uv pip install -e .
uv run pre-commit install

Run tests

make test

To generate a code coverage badge and see your code coverage, run:

make coverage

Documentation website

The documentation is based on mkdocs material, but feel free to use another framework.

You only have to set up GitHub Pages to the gh-pages branch, and .github/workflows/doc.yaml will handle the deployment.

• Preview locally:

make preview

• Footer of the site:

The footer of the documentation website is defined in overrides/partials/footer.html. If you don’t know HTML/CSS, chatGPT can help you here!

• Change main color:

In docs/stylesheets/style.css, change the color value to change the overall style of site:

:root {
  --primary-color: #0096c7;
}

Make a new PyPI release

New PyPI releases are made via 2 scripts:

• release.sh

  • When you run .scripts/release.sh 1.0.0 (to release the 1.0.0 version, for instance), it will commit, tag that commit and push.

• .github/workflows/pypi.yaml

  • When a git tag matching v1.2.3 format is pushed, it will make a new PyPI release (in short).

This relies on trusted publishing, which you need to configure. This step is important (on security aspects), so make sure you understand what is happening. Feel free to spend some time reading the scripts and the official documentation.

Since the distribution of new versions is reserved for a few people, feel free to remove it from the git tracker with:

git rm --cached scripts/release.sh

If you don’t plan to make PyPI releases, just delete .scripts/release.sh and .github/workflows/pypi.yaml.

Update the README

The README.md file is dynamically generated by docs/README.qmd, a Quarto document.

This is optional (you can use a plain README.md and delete docs/README.qmd), but it has many benefits:

• it is just markdown too
• there are lots of customization options
• you can include code (for example, dynamic content)

from package_name import add_digit

# The output here is not hardcoded
print(add_digit(2, 5))

7

It works perfectly well with most IDEs. You can install Quarto here.

To generate README.md, run (make sure your venv is activated):

make readme

Still have some questions? Open an issue!