11# Contributing guide
22
3- Scanpy provides extensive [ developer documentation] [ scanpy developer guide ] , most of which applies to this project, too.
4- This document will not reproduce the entire content from there.
5- Instead, it aims at summarizing the most important information to get you started on contributing.
6-
3+ This document aims at summarizing the most important information for getting you started on contributing to this project.
74We assume that you are already familiar with git and with making pull requests on GitHub.
8- If not, please refer to the [ scanpy developer guide] [ ] .
95
6+ For more extensive tutorials, that also cover the absolute basics,
7+ please refer to other resources such as the [ pyopensci tutorials] [ ] ,
8+ the [ scientific Python tutorials] [ ] , or the [ scanpy developer guide] [ ] .
9+
10+ [ pyopensci tutorials ] : https://www.pyopensci.org/learn.html
11+ [ scientific Python tutorials ] : https://learn.scientific-python.org/development/tutorials/
1012[ scanpy developer guide ] : https://scanpy.readthedocs.io/en/latest/dev/index.html
1113
14+ :::{tip} The * hatch* project manager
15+
16+ We highly recommend to familiarize yourself with [ ` hatch ` ] [ hatch ] .
17+ Hatch is a Python project manager that
18+
19+ - manages virtual environments, separately for development, testing and building the documentation.
20+ Separating the environments is useful to avoid dependency conflicts.
21+ - allows to run tests locally in different environments (e.g. different python versions)
22+ - allows to run tasks defined in ` pyproject.toml ` , e.g. to build documentation.
23+
24+ While the project is setup with ` hatch ` in mind,
25+ it is still possible to use different tools to manage dependencies, such as ` uv ` or ` pip ` .
26+
27+ :::
28+
29+ [ hatch ] : https://hatch.pypa.io/latest/
30+
1231## Installing dev dependencies
1332
1433In addition to the packages needed to _ use_ this package,
1534you need additional python packages to [ run tests] ( #writing-tests ) and [ build the documentation] ( #docs-building ) .
1635
1736:::::{tabs}
1837::::{group-tab} Hatch
19- The easiest way is to get familiar with [ hatch environments] [ ] , with which these tasks are simply:
38+
39+ On the command line, you typically interact with hatch through its command line interface (CLI).
40+ Running one of the following commands will automatically resolve the environments for testing and
41+ building the documentation in the background:
2042
2143``` bash
2244hatch test # defined in the table [tool.hatch.envs.hatch-test] in pyproject.toml
2345hatch run docs:build # defined in the table [tool.hatch.envs.docs]
2446```
2547
48+ When using an IDE such as VS Code,
49+ you’ll have to point the editor at the paths to the virtual environments manually.
50+ The environment you typically want to use as your main development environment is the ` hatch-test `
51+ environment with the latest Python version.
52+
53+ To get a list of all environments for your projects, run
54+
55+ ``` bash
56+ hatch env show -i
57+ ```
58+
59+ This will list “Standalone” environments and a table of “Matrix” environments like the following:
60+
61+ ```
62+ +------------+---------+--------------------------+----------+---------------------------------+-------------+
63+ | Name | Type | Envs | Features | Dependencies | Scripts |
64+ +------------+---------+--------------------------+----------+---------------------------------+-------------+
65+ | hatch-test | virtual | hatch-test.py3.10-stable | dev | coverage-enable-subprocess==1.0 | cov-combine |
66+ | | | hatch-test.py3.13-stable | test | coverage[toml]~=7.4 | cov-report |
67+ | | | hatch-test.py3.13-pre | | pytest-mock~=3.12 | run |
68+ | | | | | pytest-randomly~=3.15 | run-cov |
69+ | | | | | pytest-rerunfailures~=14.0 | |
70+ | | | | | pytest-xdist[psutil]~=3.5 | |
71+ | | | | | pytest~=8.1 | |
72+ +------------+---------+--------------------------+----------+---------------------------------+-------------+
73+ ```
74+
75+ From the ` Envs ` column, select the environment name you want to use for development.
76+ In this example, it would be ` hatch-test.py3.13-stable ` .
77+
78+ Next, create the environment with
79+
80+ ``` bash
81+ hatch env create hatch-test.py3.13-stable
82+ ```
83+
84+ Then, obtain the path to the environment using
85+
86+ ``` bash
87+ hatch env find hatch-test.py3.13-stable
88+ ```
89+
90+ In case you are using VScode, now open the command palette (Ctrl+Shift+P) and search for ` Python: Select Interpreter ` .
91+ Choose ` Enter Interpreter Path ` and paste the path to the virtual environment from above.
92+
93+ In this future, this may become easier through a hatch vscode extension.
94+
95+ ::::
96+
97+ ::::{group-tab} uv
98+
99+ A popular choice for managing virtual environments is [ uv] [ ] .
100+ The main disadvantage compared to hatch is that it supports only a single environment per project at a time,
101+ which requires you to mix the dependencies for running tests and building docs.
102+ This can have undesired side-effects,
103+ such as requiring to install a lower version of a library your project depends on,
104+ only because an outdated sphinx plugin pins an older version.
105+
106+ To initalize a virtual environment in the ` .venv ` directory of your project, simply run
107+
108+ ``` bash
109+ uv sync --all-extras
110+ ```
111+
112+ The ` .venv ` directory is typically automatically discovered by IDEs such as VS Code.
113+
26114::::
27115
28116::::{group-tab} Pip
29- If you prefer managing environments manually, you can use ` pip ` :
117+
118+ Pip is nowadays mostly superseded by environment manager such as [ hatch] [ ] .
119+ However, for the sake of completeness, and since it’s ubiquitously available,
120+ we describe how you can manage environments manually using ` pip ` :
30121
31122``` bash
32- cd cell-annotator
33123python3 -m venv .venv
34124source .venv/bin/activate
35125pip install -e " .[dev,test,doc]"
36126```
37127
128+ The ` .venv ` directory is typically automatically discovered by IDEs such as VS Code.
129+
38130::::
39131:::::
40132
41133[ hatch environments ] : https://hatch.pypa.io/latest/tutorials/environment/basic-usage/
134+ [ uv ] : https://docs.astral.sh/uv/
42135
43136## Code-style
44137
@@ -55,7 +148,7 @@ in the root of the repository.
55148Pre-commit will automatically download all dependencies when it is run for the first time.
56149
57150Alternatively, you can rely on the [ pre-commit.ci] [ ] service enabled on GitHub.
58- If you didn' t run ` pre-commit ` before pushing changes to GitHub it will automatically commit fixes to your pull request, or show an error message.
151+ If you didn’ t run ` pre-commit ` before pushing changes to GitHub it will automatically commit fixes to your pull request, or show an error message.
59152
60153If pre-commit.ci added a commit on a branch you still have been working on locally, simply use
61154
@@ -102,6 +195,14 @@ hatch test --all # test with all supported Python versions
102195
103196::::
104197
198+ ::::{group-tab} uv
199+
200+ ``` bash
201+ uv run pytest
202+ ```
203+
204+ ::::
205+
105206::::{group-tab} Pip
106207
107208``` bash
@@ -118,12 +219,17 @@ in the root of the repository.
118219
119220### Continuous integration
120221
121- Continuous integration will automatically run the tests on all pull requests and test
222+ Continuous integration via GitHub actions will automatically run the tests on all pull requests and test
122223against the minimum and maximum supported Python version.
123224
124- Additionally, there' s a CI job that tests against pre-releases of all dependencies (if there are any).
225+ Additionally, there’ s a CI job that tests against pre-releases of all dependencies (if there are any).
125226The purpose of this check is to detect incompatibilities of new package versions early on and
126- gives you time to fix the issue or reach out to the developers of the dependency before the package is released to a wider audience.
227+ gives you time to fix the issue or reach out to the developers of the dependency before the package
228+ is released to a wider audience.
229+
230+ The CI job is defined in ` .github/workflows/test.yaml ` ,
231+ however the single point of truth for CI jobs is the Hatch test matrix defined in ` pyproject.toml ` .
232+ This means that local testing via hatch and remote testing on CI tests against the same python versions and uses the same environments.
127233
128234## Publishing a release
129235
@@ -193,7 +299,7 @@ please check out [this feature request][issue-render-notebooks] in the `cookiecu
193299
194300(docs-building)=
195301
196- #### Building the docs locally
302+ ### Building the docs locally
197303
198304:::::{tabs}
199305::::{group-tab} Hatch
@@ -205,12 +311,22 @@ hatch run docs:open
205311
206312::::
207313
314+ ::::{group-tab} uv
315+
316+ ``` bash
317+ cd docs
318+ uv run sphinx-build -M html . _build -W
319+ (xdg-)open _build/html/index.html
320+ ```
321+
322+ ::::
323+
208324::::{group-tab} Pip
209325
210326``` bash
211327source .venv/bin/activate
212328cd docs
213- make html
329+ sphinx-build -M html . _build -W
214330(xdg-)open _build/html/index.html
215331```
216332
0 commit comments