Skip to content

Commit a5e535b

Browse files
xarvexCyanVoxel
xarvex
and
CyanVoxel
authored
feat(ci): development tooling refresh and split documentation (#867)
* feat(nix/shell): use uv for faster evaluation * feat(contrib): define developer configurations * feat(ci): configure pre-commit to use project dependencies, add mypy * fix(docs): typo * docs: split develop and install, document integrations * nit(contrib): add shellcheck directive to envrc's * docs: move third-party dependencies to install page * nit(flake): use pythonPackages variable --------- Co-authored-by: Travis Abendshien <46939827+CyanVoxel@users.noreply.github.com>
1 parent ed6ac24 commit a5e535b

File tree

13 files changed

+353
-255
lines changed

13 files changed

+353
-255
lines changed

‎.envrc.recommended

Lines changed: 0 additions & 18 deletions
This file was deleted.

‎.pre-commit-config.yaml

Lines changed: 23 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,26 @@
1+
---
12
repos:
2-
- repo: https://github.com/astral-sh/ruff-pre-commit
3-
# Ruff version.
4-
rev: v0.6.4
3+
- repo: local
54
hooks:
6-
- id: ruff-format
5+
- id: mypy
6+
name: mypy
7+
entry: mypy
8+
language: system
9+
types_or: [python, pyi]
10+
require_serial: true
11+
712
- id: ruff
13+
name: ruff
14+
entry: ruff check
15+
language: system
16+
types_or: [python, pyi, jupyter]
17+
args: [--force-exclude]
18+
require_serial: true
19+
20+
- id: ruff-format
21+
name: ruff-format
22+
entry: ruff format
23+
language: system
24+
types_or: [python, pyi, jupyter]
25+
args: [--force-exclude, --check]
26+
require_serial: true

‎contrib/.envrc-nix

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# shellcheck shell=bash
2+
3+
# If you wish to use this file, symlink or copy it to `.envrc` for direnv to read it.
4+
# This will use the Nix flake development shell.
5+
#
6+
# ln -s contrib/.envrc-nix .envrc
7+
8+
if ! has nix_direnv_version || ! nix_direnv_version 3.0.6; then
9+
source_url "https://raw.githubusercontent.com/nix-community/nix-direnv/3.0.6/direnvrc" "sha256-RYcUJaRMf8oF5LznDrlCXbkOQrywm0HDv1VjYGaJGdM="
10+
fi
11+
12+
watch_file nix/shell.nix pyproject.toml
13+
14+
use flake
15+
16+
# Only watch now, or direnv will execute again if created or modified by itself.
17+
watch_file "${UV_PROJECT_ENVIRONMENT:-.venv}"/bin/activate
18+
19+
# vi: ft=bash

‎contrib/.envrc-uv

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# shellcheck shell=bash
2+
3+
# If you wish to use this file, symlink or copy it to `.envrc` for direnv to read it.
4+
# This will use a virtual environment created by uv.
5+
#
6+
# ln -s contrib/.envrc-uv .envrc
7+
8+
watch_file .python-version pyproject.toml uv.lock
9+
10+
venv="$(expand_path "${UV_PROJECT_ENVIRONMENT:-.venv}")"
11+
12+
if [ ! -f "${venv}"/bin/activate ]; then
13+
printf '%s\n' 'Generating virtual environment...' >&2
14+
rm -rf "${venv}"
15+
uv venv "${venv}"
16+
fi
17+
18+
# Only watch now, or direnv will execute again if created or modified by itself.
19+
watch_file "${venv}"/bin/activate
20+
21+
# shellcheck disable=SC1091
22+
source "${venv}"/bin/activate
23+
24+
if [ ! -f "${venv}"/pyproject.toml ] || ! diff --brief pyproject.toml "${venv}"/pyproject.toml >/dev/null; then
25+
printf '%s\n' 'Installing dependencies, pyproject.toml changed...' >&2
26+
uv pip install --quiet --editable '.[dev]'
27+
cp pyproject.toml "${venv}"/pyproject.toml
28+
fi
29+
30+
pre-commit install
31+
32+
# vi: ft=bash

‎contrib/.vscode/launch.json

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
{
2+
"version": "0.2.0",
3+
"configurations": [
4+
{
5+
"name": "TagStudio",
6+
"type": "python",
7+
"request": "launch",
8+
"program": "${workspaceRoot}/src/tagstudio/main.py",
9+
"console": "integratedTerminal",
10+
"justMyCode": true,
11+
"args": [
12+
"-o",
13+
"~/Documents/Example"
14+
]
15+
}
16+
]
17+
}

‎docs/develop.md

Lines changed: 180 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,180 @@
1+
# Developing
2+
3+
If you wish to develop for TagStudio, you'll need to create a development environment by installing the required dependencies. You have a number of options depending on your level of experience and familiarly with existing Python toolchains.
4+
5+
<!-- prettier-ignore -->
6+
!!! tip "Contributing"
7+
If you wish to contribute to TagStudio's development, please read our [CONTRIBUTING.md](https://github.com/TagStudioDev/TagStudio/blob/main/CONTRIBUTING.md)!
8+
9+
## Install Python
10+
11+
Python [3.12](https://www.python.org/downloads) is required to develop for TagStudio. Any version matching "Python 3.12.x" should work, with "x" being any number. Alternatively you can use a tool such as [pyenv](https://github.com/pyenv/pyenv) to install this version of Python without affecting any existing Python installations on your system. Tools such as [uv](#installing-with-uv) can also install Python versions.
12+
13+
<!-- prettier-ignore -->
14+
!!! info "Python Aliases"
15+
Depending on your system, Python may be called `python`, `py`, `python3`, or `py3`. These instructions use the alias `python` for consistency.
16+
17+
If you already have Python installed on your system, you can check the version by running the following command:
18+
19+
```sh
20+
python --version
21+
```
22+
23+
---
24+
25+
#### Installing with pyenv
26+
27+
If you choose to install Python using pyenv, please refer to the following instructions:
28+
29+
1. Follow pyenv's [install instructions](https://github.com/pyenv/pyenv/?tab=readme-ov-file#installation) for your system.
30+
2. Install the appropriate Python version with pyenv by running `pyenv install 3.12` (This will **not** mess with your existing Python installation).
31+
3. Navigate to the repository root folder in your terminal and run `pyenv local 3.12`. You could alternatively use `pyenv shell 3.12` or `pyenv global 3.12` instead to set the Python version for the current terminal session or the entire system respectively, however using `local` is recommended.
32+
33+
---
34+
35+
### Installing Dependencies
36+
37+
To install the required dependencies, you can use a dependency manager such as [uv](https://docs.astral.sh/uv) or [Poetry 2.0](https://python-poetry.org). Alternatively you can create a virtual environment and manually install the dependencies yourself.
38+
39+
#### Installing with uv
40+
41+
If using [uv](https://docs.astral.sh/uv), you can install the dependencies for TagStudio with the following command:
42+
43+
```sh
44+
uv pip install -e .[dev]
45+
```
46+
47+
A reference `.envrc` is provided for use with [direnv](#direnv), see [`contrib/.envrc-uv`](https://github.com/TagStudioDev/TagStudio/blob/main/contrib/.envrc-uv).
48+
49+
---
50+
51+
#### Installing with Poetry
52+
53+
If using [Poetry](https://python-poetry.org), you can install the dependencies for TagStudio with the following command:
54+
55+
```sh
56+
poetry install --with dev
57+
```
58+
59+
---
60+
61+
#### Manual Installation
62+
63+
If you choose to manually set up a virtual environment and install dependencies instead of using a dependency manager, please refer to the following instructions:
64+
65+
<!-- prettier-ignore -->
66+
!!! tip "Virtual Environments"
67+
Learn more about setting up a virtual environment with Python's [official tutorial](https://docs.python.org/3/tutorial/venv.html).
68+
69+
1. In the root repository directory, create a python virtual environment:
70+
71+
```sh
72+
python -m venv .venv
73+
```
74+
75+
2. Activate your environment:
76+
77+
- Windows w/Powershell: `.venv\Scripts\Activate.ps1`
78+
- Windows w/Command Prompt: `.venv\Scripts\activate.bat`
79+
- Linux/macOS: `source .venv/bin/activate`
80+
81+
<!-- prettier-ignore -->
82+
!!! info "Supported Shells"
83+
Depending on your system, the regular activation script _might_ not work on alternative shells. In this case, refer to the table below for supported shells:
84+
85+
| Shell | Script |
86+
| ---------: | :------------------------ |
87+
| Bash/ZSH | `.venv/bin/activate` |
88+
| Fish | `.venv/bin/activate.fish` |
89+
| CSH/TCSH | `.venv/bin/activate.csh` |
90+
| PowerShell | `.venv/bin/activate.ps1` |
91+
92+
3. Use the following PIP command to create an editable installation and install the required development dependencies:
93+
94+
```sh
95+
pip install -e .[dev]
96+
```
97+
98+
## Nix(OS)
99+
100+
If using [Nix](https://nixos.org/), there is a development environment already provided in the [flake](https://wiki.nixos.org/wiki/Flakes) that is accessible with the following command:
101+
102+
```sh
103+
nix develop
104+
```
105+
106+
A reference `.envrc` is provided for use with [direnv](#direnv), see [`contrib/.envrc-nix`](https://github.com/TagStudioDev/TagStudio/blob/main/contrib/.envrc-nix).
107+
108+
## Tooling
109+
110+
### Editor Integration
111+
112+
The entry point for TagStudio is `src/tagstudio/main.py`. You can target this file from your IDE to run or connect a debug session. The example(s) below show off example launch scripts for different IDEs. Here you can also take advantage of [launch arguments](./usage.md/#launch-arguments) to pass your own test [libraries](./library/index.md) to use while developing. You can find more editor configurations in [`contrib`](https://github.com/TagStudioDev/TagStudio/tree/main/contrib).
113+
114+
<!-- prettier-ignore -->
115+
=== "VS Code"
116+
```json title=".vscode/launch.json"
117+
{
118+
"version": "0.2.0",
119+
"configurations": [
120+
{
121+
"name": "TagStudio",
122+
"type": "python",
123+
"request": "launch",
124+
"program": "${workspaceRoot}/src/tagstudio/main.py",
125+
"console": "integratedTerminal",
126+
"justMyCode": true,
127+
"args": ["-o", "~/Documents/Example"]
128+
}
129+
]
130+
}
131+
```
132+
133+
### pre-commit
134+
135+
There is a [pre-commit](https://pre-commit.com/) configuration that will run through some checks before code is committed. Namely, mypy and the Ruff linter and formatter will check your code, catching those nits right away.
136+
137+
Once you have pre-commit installed, just run:
138+
139+
```sh
140+
pre-commit install
141+
```
142+
143+
From there, Git will automatically run through the hooks during commit actions!
144+
145+
### direnv
146+
147+
You can automatically enter this development shell, and keep your user shell, with a tool like [direnv](https://direnv.net/). Some reference `.envrc` files are provided in the repository at [`contrib`](https://github.com/TagStudioDev/TagStudio/tree/main/contrib).
148+
149+
Two currently available are for [Nix](#nixos) and [uv](#installing-with-uv), to use one:
150+
151+
```sh
152+
ln -s .envrc-$variant .envrc
153+
```
154+
155+
You will have to allow usage of it.
156+
157+
<!-- prettier-ignore -->
158+
!!! warning "direnv Security Framework"
159+
These files are generally a good idea to check, as they execute commands on directory load. direnv has a security framework to only run `.envrc` files you have allowed, and does keep track on if it has changed. So, with that being said, the file may need to be allowed again if modifications are made.
160+
161+
```sh
162+
cat .envrc # You are checking them, right?
163+
direnv allow
164+
```
165+
166+
## Building
167+
168+
To build your own executables of TagStudio, first follow the steps in "[Installing Dependencies](#installing-dependencies)." Once that's complete, run the following PyInstaller command:
169+
170+
```
171+
pyinstaller tagstudio.spec
172+
```
173+
174+
If you're on Windows or Linux and wish to build a portable executable, then pass the following flag:
175+
176+
```
177+
pyinstaller tagstudio.spec -- --portable
178+
```
179+
180+
The resulting executable file(s) will be located in a new folder named "dist".

0 commit comments

Comments
 (0)