Repository navigation
Expand file tree
/
Copy pathREADME.qmd
More file actions
118 lines (87 loc) · 3.94 KB
/
Copy pathREADME.qmd
File metadata and controls
118 lines (87 loc) · 3.94 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
---
title: template-python
format:
gfm:
toc: false
preserve-yaml: false
---
<!-- README.md is generated from README.qmd: edit the .qmd and run `make readme`. -->
[](https://github.com/max-models/template-python/actions/workflows/test_pytest.yml)
[](https://github.com/max-models/template-python/actions/workflows/static_analysis.yml)
[](https://max-models.github.io/template-python/)
[](https://codecov.io/gh/max-models/template-python)
[](https://pypi.org/project/template-python/)
[](https://pypi.org/project/template-python/)
Template repository for Python projects: a `src/` package with a console entry point,
`pytest` tests, GitHub Actions for tests, static analysis, tutorials, documentation and
PyPI publishing, and an [Astro](https://astro.build/) + [Starlight](https://starlight.astro.build/)
documentation site.
Documentation: <https://max-models.github.io/template-python/>
## Use the template
Create a repository from this template, then rename the package:
```bash
bash setup_project.sh my-app
rm setup_project.sh
```
This replaces `template-python` with `my-app` everywhere, moves `src/app` to `src/my_app`,
and points the entry point, tests and docs at it.
## Install
With [uv](https://docs.astral.sh/uv/):
```bash
make install # uv sync --extra dev, plus the pre-commit hooks
uv run template-python
```
Or create and activate a Python environment (3.10 or newer):
```bash
python -m venv env
source env/bin/activate
pip install --upgrade pip
```
Install the code and requirements with pip:
```bash
pip install -e .
```
Run the code with:
```bash
template-python
```
The `test`, `docs` and `dev` extras install the test runner, the documentation tooling and
the linters:
```bash
pip install -e ".[dev]"
```
## Development
Formatting and linting use [ruff](https://docs.astral.sh/ruff/), type checking
[pyright](https://microsoft.github.io/pyright/), run by [pre-commit](https://pre-commit.com/)
and in CI:
```bash
make lint # ruff check, ruff format --check, pyright
make test # pytest with coverage
```
Commit messages follow [Conventional Commits](https://www.conventionalcommits.org/); see
[CONTRIBUTING.md](CONTRIBUTING.md).
## Build docs
The documentation in `docs/` is an Astro + Starlight site: hand-written pages, the notebooks
in `tutorials/` executed and published as pages, complete Python scripts in `examples/`
published with their plots, and the API reference generated from the
docstrings with [starlight-pydocs](https://ewels.github.io/starlight-pydocs/). It needs
Node 22 or newer.
```bash
make docs-install # npm packages and the Python docs extra
make docs-notebooks # execute tutorials/*.ipynb and convert them to pages
make docs-examples # run examples/*.py and publish their plots
make docs-dev # live preview at http://localhost:4321/template-python/
make docs-build # the static site in docs/dist
```
## Build the README
`README.md` is rendered from `README.qmd` with [Quarto](https://quarto.org/):
```bash
make readme
```
## Releases
Before merging a release to `main`, update the version in `pyproject.toml`,
`src/app/__init__.py` and `CITATION.cff` (including its release date), and add the release
notes to `CHANGELOG.md`. The push to `main` creates a GitHub release with a `vX.Y.Z` tag and
publishes the package to PyPI with trusted publishing (OIDC). The one-time PyPI and GitHub
configuration is described in the
[publishing tutorial](https://max-models.github.io/template-python/development/publishing/).