|
| 1 | +# Contributing guide |
| 2 | + |
| 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 | + |
| 7 | +We 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][]. |
| 9 | + |
| 10 | +[scanpy developer guide]: https://scanpy.readthedocs.io/en/latest/dev/index.html |
| 11 | + |
| 12 | +## Installing dev dependencies |
| 13 | + |
| 14 | +In addition to the packages needed to _use_ this package, |
| 15 | +you need additional python packages to [run tests](#writing-tests) and [build the documentation](#docs-building). |
| 16 | + |
| 17 | +:::::{tabs} |
| 18 | +::::{group-tab} Hatch |
| 19 | +The easiest way is to get familiar with [hatch environments][], with which these tasks are simply: |
| 20 | + |
| 21 | +```bash |
| 22 | +hatch test # defined in the table [tool.hatch.envs.hatch-test] in pyproject.toml |
| 23 | +hatch run docs:build # defined in the table [tool.hatch.envs.docs] |
| 24 | +``` |
| 25 | + |
| 26 | +:::: |
| 27 | + |
| 28 | +::::{group-tab} Pip |
| 29 | +If you prefer managing environments manually, you can use `pip`: |
| 30 | + |
| 31 | +```bash |
| 32 | +cd troutpy |
| 33 | +python3 -m venv .venv |
| 34 | +source .venv/bin/activate |
| 35 | +pip install -e ".[dev,test,doc]" |
| 36 | +``` |
| 37 | + |
| 38 | +:::: |
| 39 | +::::: |
| 40 | + |
| 41 | +[hatch environments]: https://hatch.pypa.io/latest/tutorials/environment/basic-usage/ |
| 42 | + |
| 43 | +## Code-style |
| 44 | + |
| 45 | +This package uses [pre-commit][] to enforce consistent code-styles. |
| 46 | +On every commit, pre-commit checks will either automatically fix issues with the code, or raise an error message. |
| 47 | + |
| 48 | +To enable pre-commit locally, simply run |
| 49 | + |
| 50 | +```bash |
| 51 | +pre-commit install |
| 52 | +``` |
| 53 | + |
| 54 | +in the root of the repository. |
| 55 | +Pre-commit will automatically download all dependencies when it is run for the first time. |
| 56 | + |
| 57 | +Alternatively, 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. |
| 59 | + |
| 60 | +If pre-commit.ci added a commit on a branch you still have been working on locally, simply use |
| 61 | + |
| 62 | +```bash |
| 63 | +git pull --rebase |
| 64 | +``` |
| 65 | + |
| 66 | +to integrate the changes into yours. |
| 67 | +While the [pre-commit.ci][] is useful, we strongly encourage installing and running pre-commit locally first to understand its usage. |
| 68 | + |
| 69 | +Finally, most editors have an _autoformat on save_ feature. |
| 70 | +Consider enabling this option for [ruff][ruff-editors] and [prettier][prettier-editors]. |
| 71 | + |
| 72 | +[pre-commit]: https://pre-commit.com/ |
| 73 | +[pre-commit.ci]: https://pre-commit.ci/ |
| 74 | +[ruff-editors]: https://docs.astral.sh/ruff/integrations/ |
| 75 | + |
| 76 | +[prettier-editors]: https://prettier.io/docs/en/editors.html |
| 77 | + |
| 78 | +(writing-tests)= |
| 79 | + |
| 80 | +## Writing tests |
| 81 | + |
| 82 | +This package uses [pytest][] for automated testing. |
| 83 | +Please write {doc}`scanpy:dev/testing` for every function added to the package. |
| 84 | + |
| 85 | +Most IDEs integrate with pytest and provide a GUI to run tests. |
| 86 | +Just point yours to one of the environments returned by |
| 87 | + |
| 88 | +```bash |
| 89 | +hatch env create hatch-test # create test environments for all supported versions |
| 90 | +hatch env find hatch-test # list all possible test environment paths |
| 91 | +``` |
| 92 | + |
| 93 | +Alternatively, you can run all tests from the command line by executing |
| 94 | + |
| 95 | +:::::{tabs} |
| 96 | +::::{group-tab} Hatch |
| 97 | + |
| 98 | +```bash |
| 99 | +hatch test # test with the highest supported Python version |
| 100 | +# or |
| 101 | +hatch test --all # test with all supported Python versions |
| 102 | +``` |
| 103 | + |
| 104 | +:::: |
| 105 | + |
| 106 | +::::{group-tab} Pip |
| 107 | + |
| 108 | +```bash |
| 109 | +source .venv/bin/activate |
| 110 | +pytest |
| 111 | +``` |
| 112 | + |
| 113 | +:::: |
| 114 | +::::: |
| 115 | + |
| 116 | +in the root of the repository. |
| 117 | + |
| 118 | +[pytest]: https://docs.pytest.org/ |
| 119 | + |
| 120 | +### Continuous integration |
| 121 | + |
| 122 | +Continuous integration will automatically run the tests on all pull requests and test |
| 123 | +against the minimum and maximum supported Python version. |
| 124 | + |
| 125 | +Additionally, there's a CI job that tests against pre-releases of all dependencies (if there are any). |
| 126 | +The purpose of this check is to detect incompatibilities of new package versions early on and |
| 127 | +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. |
| 128 | + |
| 129 | +## Publishing a release |
| 130 | + |
| 131 | +### Updating the version number |
| 132 | + |
| 133 | +Before making a release, you need to update the version number in the `pyproject.toml` file. |
| 134 | +Please adhere to [Semantic Versioning][semver], in brief |
| 135 | + |
| 136 | +> Given a version number MAJOR.MINOR.PATCH, increment the: |
| 137 | +> |
| 138 | +> 1. MAJOR version when you make incompatible API changes, |
| 139 | +> 2. MINOR version when you add functionality in a backwards compatible manner, and |
| 140 | +> 3. PATCH version when you make backwards compatible bug fixes. |
| 141 | +> |
| 142 | +> Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format. |
| 143 | +
|
| 144 | +Once you are done, commit and push your changes and navigate to the "Releases" page of this project on GitHub. |
| 145 | +Specify `vX.X.X` as a tag name and create a release. |
| 146 | +For more information, see [managing GitHub releases][]. |
| 147 | +This will automatically create a git tag and trigger a Github workflow that creates a release on [PyPI][]. |
| 148 | + |
| 149 | +[semver]: https://semver.org/ |
| 150 | +[managing GitHub releases]: https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository |
| 151 | +[pypi]: https://pypi.org/ |
| 152 | + |
| 153 | +## Writing documentation |
| 154 | + |
| 155 | +Please write documentation for new or changed features and use-cases. |
| 156 | +This project uses [sphinx][] with the following features: |
| 157 | + |
| 158 | +- The [myst][] extension allows to write documentation in markdown/Markedly Structured Text |
| 159 | +- [Numpy-style docstrings][numpydoc] (through the [napoloen][numpydoc-napoleon] extension). |
| 160 | +- Jupyter notebooks as tutorials through [myst-nb][] (See [Tutorials with myst-nb](#tutorials-with-myst-nb-and-jupyter-notebooks)) |
| 161 | +- [sphinx-autodoc-typehints][], to automatically reference annotated input and output types |
| 162 | +- Citations (like {cite:p}`Virshup_2023`) can be included with [sphinxcontrib-bibtex](https://sphinxcontrib-bibtex.readthedocs.io/) |
| 163 | + |
| 164 | +See scanpy’s {doc}`scanpy:dev/documentation` for more information on how to write your own. |
| 165 | + |
| 166 | +[sphinx]: https://www.sphinx-doc.org/en/master/ |
| 167 | +[myst]: https://myst-parser.readthedocs.io/en/latest/intro.html |
| 168 | +[myst-nb]: https://myst-nb.readthedocs.io/en/latest/ |
| 169 | +[numpydoc-napoleon]: https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html |
| 170 | +[numpydoc]: https://numpydoc.readthedocs.io/en/latest/format.html |
| 171 | +[sphinx-autodoc-typehints]: https://github.com/tox-dev/sphinx-autodoc-typehints |
| 172 | + |
| 173 | +### Tutorials with myst-nb and jupyter notebooks |
| 174 | + |
| 175 | +The documentation is set-up to render jupyter notebooks stored in the `docs/notebooks` directory using [myst-nb][]. |
| 176 | +Currently, only notebooks in `.ipynb` format are supported that will be included with both their input and output cells. |
| 177 | +It is your responsibility to update and re-run the notebook whenever necessary. |
| 178 | + |
| 179 | +If you are interested in automatically running notebooks as part of the continuous integration, |
| 180 | +please check out [this feature request][issue-render-notebooks] in the `cookiecutter-scverse` repository. |
| 181 | + |
| 182 | +[issue-render-notebooks]: https://github.com/scverse/cookiecutter-scverse/issues/40 |
| 183 | + |
| 184 | +#### Hints |
| 185 | + |
| 186 | +- If you refer to objects from other packages, please add an entry to `intersphinx_mapping` in `docs/conf.py`. |
| 187 | + Only if you do so can sphinx automatically create a link to the external documentation. |
| 188 | +- If building the documentation fails because of a missing link that is outside your control, |
| 189 | + you can add an entry to the `nitpick_ignore` list in `docs/conf.py` |
| 190 | + |
| 191 | +(docs-building)= |
| 192 | + |
| 193 | +#### Building the docs locally |
| 194 | + |
| 195 | +:::::{tabs} |
| 196 | +::::{group-tab} Hatch |
| 197 | + |
| 198 | +```bash |
| 199 | +hatch run docs:build |
| 200 | +hatch run docs:open |
| 201 | +``` |
| 202 | + |
| 203 | +:::: |
| 204 | + |
| 205 | +::::{group-tab} Pip |
| 206 | + |
| 207 | +```bash |
| 208 | +source .venv/bin/activate |
| 209 | +cd docs |
| 210 | +make html |
| 211 | +(xdg-)open _build/html/index.html |
| 212 | +``` |
| 213 | + |
| 214 | +:::: |
| 215 | +::::: |
0 commit comments