Skip to content

Commit

Permalink
fix: update contributing guide
Browse files Browse the repository at this point in the history
  • Loading branch information
kai687 committed Jan 29, 2025
1 parent 3b043ca commit b125b7d
Show file tree
Hide file tree
Showing 3 changed files with 19 additions and 54 deletions.
65 changes: 15 additions & 50 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,61 +3,26 @@
This project is open source.
All contributions are welcome.

## Set up development environment (fast)
## Set up development environment

If you just want to edit the docs, or make a few small changes to the code,
and you have Python 3.8, 3.9, 3.10, 3.11, or 3.12 installed,
run these commands to install the dependencies:
This project uses [`uv`](https://docs.astral.sh/uv/) for package and tool management
and [`nox`](https://nox.thea.codes/en/stable/index.html) to define tasks,
such as building the docs or running tests.

```sh
pip install -U nox poetry
To install `nox` with `uv`, run:

# Run nox session, for example, to build the docs
nox -s docs -p 3.12
```sh
uv tool install nox
```

Replace the Python version with the one that's installed on your system.

## Set up development environment (reproducible, isolated)

It's best if you set up a reproducible development environment,
where all applications are as isolated as possible.

1. To run specific versions of Python, install a Python version manager,
such as `pyenv` or `mise`.

1. Install a specific Python version, for example, with `mise`:

```sh
mise install [email protected]
```

1. Specify a Python version, either locally or globally.
## Run sessions

1. Install `pipx` to install Python applications into isolated environments.
To list the available sessions, run: `nox -ls`.
To run a specific session, run: {samp}`nox -s {SESSION}`,
append `-p 3.13` to run the session only with the latest supported Python version.

```sh
pip install -U pipx
```
For example, to build the docs with Python 3.13 and start a server for a live preview, run:

1. Install `Poetry` and `Nox`:

```sh
pipx install poetry
pipx install nox
```

## Tools

This project uses [Poetry](https://python-poetry.org/) to build Python packages and manage dependencies.

This project uses [Nox](https://nox.thea.codes/en/stable/) to run tasks,
such as linting, testing, and building the docs,
in isolated virtual environments.
This makes running these tasks more predictable.
All asks are defined in the file `noxfile.py` as _sessions_.

To get an overview over all defined sessions, run `nox -ls`.
To run a specific session, run {samp}`nox -s {SESSION}`.

To build the docs and start a development server, run `nox -s docs -p 3.12 -- --live`.
```sh
nox -s docs -p 3.13 -- --live
```
2 changes: 1 addition & 1 deletion noxfile.py
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@

nox.options.stop_on_first_error = True
nox.options.default_venv_backend = "uv"
nox.options.sessions = ["tests", "typecheck"]
nox.options.sessions = ["tests", "typecheck", "docs"]

python_versions = ["3.9", "3.13"]

Expand Down
6 changes: 3 additions & 3 deletions uv.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

0 comments on commit b125b7d

Please sign in to comment.