diff --git a/.cruft.json b/.cruft.json
index cf0455b..25dc3ee 100644
--- a/.cruft.json
+++ b/.cruft.json
@@ -1,7 +1,7 @@
 {
   "template": "https://github.com/scverse/cookiecutter-scverse",
-  "commit": "c96cadaa981a71113cc97ada8e5085188ed22ed7",
-  "checkout": "v0.1.1",
+  "commit": "57f6267716826dad73baba46dc3c00fe7262c459",
+  "checkout": "v0.2.0",
   "context": {
     "cookiecutter": {
       "project_name": "multi-view-atlas",
diff --git a/.flake8 b/.flake8
deleted file mode 100644
index 10cfc5a..0000000
--- a/.flake8
+++ /dev/null
@@ -1,57 +0,0 @@
-# Can't yet be moved to the pyproject.toml due to https://github.com/PyCQA/flake8/issues/234
-[flake8]
-max-line-length = 120
-ignore =
-    # line break before a binary operator -> black does not adhere to PEP8
-    W503
-    # line break occured after a binary operator -> black does not adhere to PEP8
-    W504
-    # line too long -> we accept long comment lines; black gets rid of long code lines
-    E501
-    # whitespace before : -> black does not adhere to PEP8
-    E203
-    # line break before binary operator -> black does not adhere to PEP8
-    W503
-    # missing whitespace after ,', ';', or ':' -> black does not adhere to PEP8
-    E231
-    # continuation line over-indented for hanging indent -> black does not adhere to PEP8
-    E126
-    # too many leading '#' for block comment -> this is fine for indicating sections
-    E262
-    # Do not assign a lambda expression, use a def -> lambda expression assignments are convenient
-    E731
-    # allow I, O, l as variable names -> I is the identity matrix
-    E741
-    # Missing docstring in public package
-    D104
-    # Missing docstring in public module
-    D100
-    # Missing docstring in __init__
-    D107
-    # Errors from function calls in argument defaults. These are fine when the result is immutable.
-    B008
-    # Missing docstring in magic method
-    D105
-    # format string does contain unindexed parameters
-    P101
-    # first line should end with a period [Bug: doesn't work with single-line docstrings]
-    D400
-    # First line should be in imperative mood; try rephrasing
-    D401
-exclude = .git,__pycache__,build,docs/_build,dist
-per-file-ignores =
-    tests/*: D
-    */__init__.py: F401
-rst-roles =
-    class,
-    func,
-    ref,
-    cite:p,
-    cite:t,
-rst-directives =
-    envvar,
-    exception,
-rst-substitutions =
-    version,
-extend-ignore =
-    RST307,
diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml
index 9dfd4ac..8d3ddaa 100644
--- a/.github/ISSUE_TEMPLATE/bug_report.yml
+++ b/.github/ISSUE_TEMPLATE/bug_report.yml
@@ -8,8 +8,8 @@ body:
               **Note**: Please read [this guide](https://matthewrocklin.com/blog/work/2018/02/28/minimal-bug-reports)
               detailing how to provide the necessary information for us to reproduce your bug. In brief:
                 * Please provide exact steps how to reproduce the bug in a clean Python environment.
-                * In case it's not clear what's causing this bug, please provide the data or the data generation procecure.
-                * Sometimes it is not possible to share the data but usually it is possible to replicate problems on publicly
+                * In case it's not clear what's causing this bug, please provide the data or the data generation procedure.
+                * Sometimes it is not possible to share the data, but usually it is possible to replicate problems on publicly
                   available datasets or to share a subset of your data.
 
     - type: textarea
diff --git a/.gitignore.rej b/.gitignore.rej
new file mode 100644
index 0000000..f9e6e20
--- /dev/null
+++ b/.gitignore.rej
@@ -0,0 +1,15 @@
+diff a/.gitignore b/.gitignore	(rejected hunks)
+@@ -1,9 +1,13 @@
+ # Temp files
+ .DS_Store
+ *~
++buck-out/
+ 
+ # Compiled files
++.venv/
+ __pycache__/
++.mypy_cache/
++.ruff_cache/
+ 
+ # Distribution / packaging
+ /build/
diff --git a/.pre-commit-config.yaml.rej b/.pre-commit-config.yaml.rej
new file mode 100644
index 0000000..0e0f6f7
--- /dev/null
+++ b/.pre-commit-config.yaml.rej
@@ -0,0 +1,81 @@
+diff a/.pre-commit-config.yaml b/.pre-commit-config.yaml	(rejected hunks)
+@@ -7,32 +7,28 @@ default_stages:
+ minimum_pre_commit_version: 2.16.0
+ repos:
+     - repo: https://github.com/psf/black
+-      rev: 23.3.0
++      rev: "23.3.0"
+       hooks:
+           - id: black
+-    - repo: https://github.com/pre-commit/mirrors-prettier
+-      rev: v3.0.0-alpha.9-for-vscode
+-      hooks:
+-          - id: prettier
+     - repo: https://github.com/asottile/blacken-docs
+       rev: 1.13.0
+       hooks:
+           - id: blacken-docs
+-    - repo: https://github.com/PyCQA/isort
+-      rev: 5.12.0
+-      hooks:
+-          - id: isort
+-    - repo: https://github.com/asottile/yesqa
+-      rev: v1.4.0
++    - repo: https://github.com/pre-commit/mirrors-prettier
++      rev: v3.0.0-alpha.9-for-vscode
+       hooks:
+-          - id: yesqa
+-            additional_dependencies:
+-                - flake8-tidy-imports
+-                - flake8-docstrings
+-                - flake8-rst-docstrings
+-                - flake8-comprehensions
+-                - flake8-bugbear
+-                - flake8-blind-except
++          - id: prettier
++            # Newer versions of node don't work on systems that have an older version of GLIBC
++            # (in particular Ubuntu 18.04 and Centos 7)
++            # EOL of Centos 7 is in 2024-06, we can probably get rid of this then.
++            # See https://github.com/scverse/cookiecutter-scverse/issues/143 and
++            # https://github.com/jupyterlab/jupyterlab/issues/12675
++            language_version: "17.9.1"
++    - repo: https://github.com/charliermarsh/ruff-pre-commit
++      rev: v0.0.262
++      hooks:
++          - id: ruff
++            args: [--fix, --exit-non-zero-on-fix]
+     - repo: https://github.com/pre-commit/pre-commit-hooks
+       rev: v4.4.0
+       hooks:
+@@ -43,31 +39,6 @@ repos:
+             args: [--fix=lf]
+           - id: trailing-whitespace
+           - id: check-case-conflict
+-    - repo: https://github.com/myint/autoflake
+-      rev: v2.1.1
+-      hooks:
+-          - id: autoflake
+-            args:
+-                - --in-place
+-                - --remove-all-unused-imports
+-                - --remove-unused-variable
+-                - --ignore-init-module-imports
+-    - repo: https://github.com/PyCQA/flake8
+-      rev: 6.0.0
+-      hooks:
+-          - id: flake8
+-            additional_dependencies:
+-                - flake8-tidy-imports
+-                - flake8-docstrings
+-                - flake8-rst-docstrings
+-                - flake8-comprehensions
+-                - flake8-bugbear
+-                - flake8-blind-except
+-    - repo: https://github.com/asottile/pyupgrade
+-      rev: v3.3.2
+-      hooks:
+-          - id: pyupgrade
+-            args: [--py3-plus, --py38-plus, --keep-runtime-typing]
+     - repo: local
+       hooks:
+           - id: forbid-to-commit
diff --git a/README.md b/README.md
index c54976d..eb1a1f8 100644
--- a/README.md
+++ b/README.md
@@ -3,7 +3,7 @@
 [![Tests][badge-tests]][link-tests]
 [![Documentation][badge-docs]][link-docs]
 
-[badge-tests]: https://img.shields.io/github/workflow/status/emdann/multi-view-atlas/Test/main
+[badge-tests]: https://img.shields.io/github/actions/workflow/status/emdann/multi-view-atlas/test.yaml?branch=main
 [link-tests]: https://github.com/emdann/multi-view-atlas/actions/workflows/test.yml
 [badge-docs]: https://img.shields.io/readthedocs/multi-view-atlas
 
diff --git a/docs/_templates/autosummary/class.rst b/docs/_templates/autosummary/class.rst
index 17dc123..e4665df 100644
--- a/docs/_templates/autosummary/class.rst
+++ b/docs/_templates/autosummary/class.rst
@@ -39,9 +39,6 @@ Attributes
 
 {% for item in attributes %}
 
-{{ item }}
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
 .. autoattribute:: {{ [objname, item] | join(".") }}
 {%- endfor %}
 
@@ -56,9 +53,6 @@ Methods
 {% for item in methods %}
 {%- if item != '__init__' %}
 
-{{ item }}
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
 .. automethod:: {{ [objname, item] | join(".") }}
 {%- endif -%}
 {%- endfor %}
diff --git a/docs/conf.py b/docs/conf.py
index fa02c9d..1ef4b56 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -65,7 +65,7 @@
 napoleon_include_init_with_doc = False
 napoleon_use_rtype = True  # having a separate entry generally helps readability
 napoleon_use_param = True
-myst_heading_anchors = 3  # create anchors for h1-h3
+myst_heading_anchors = 6  # create anchors for h1-h6
 myst_enable_extensions = [
     "amsmath",
     "colon_fence",
@@ -87,11 +87,11 @@
 }
 
 intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
     "anndata": ("https://anndata.readthedocs.io/en/stable/", None),
     "numpy": ("https://numpy.org/doc/stable/", None),
 }
 
-
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
@@ -110,6 +110,7 @@
 html_theme_options = {
     "repository_url": repository_url,
     "use_repository_button": True,
+    "path_to_docs": "docs/",
 }
 
 pygments_style = "default"
diff --git a/docs/contributing.md b/docs/contributing.md
new file mode 100644
index 0000000..7fcc6ed
--- /dev/null
+++ b/docs/contributing.md
@@ -0,0 +1,197 @@
+# Contributing guide
+
+Scanpy provides extensive [developer documentation][scanpy developer guide], most of which applies to this repo, too.
+This document will not reproduce the entire content from there. Instead, it aims at summarizing the most important
+information to get you started on contributing.
+
+We assume that you are already familiar with git and with making pull requests on GitHub. If not, please refer
+to the [scanpy developer guide][].
+
+## Installing dev dependencies
+
+In addition to the packages needed to _use_ this package, you need additional python packages to _run tests_ and _build
+the documentation_. It's easy to install them using `pip`:
+
+```bash
+cd multi-view-atlas
+pip install -e ".[dev,test,doc]"
+```
+
+## Code-style
+
+This template uses [pre-commit][] to enforce consistent code-styles. On every commit, pre-commit checks will either
+automatically fix issues with the code, or raise an error message. See [pre-commit checks](template_usage.md#pre-commit-checks) for
+a full list of checks enabled for this repository.
+
+To enable pre-commit locally, simply run
+
+```bash
+pre-commit install
+```
+
+in the root of the repository. Pre-commit will automatically download all dependencies when it is run for the first time.
+
+Alternatively, you can rely on the [pre-commit.ci][] service enabled on GitHub. 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.
+
+If pre-commit.ci added a commit on a branch you still have been working on locally, simply use
+
+```bash
+git pull --rebase
+```
+
+to integrate the changes into yours.
+While the [pre-commit.ci][] is useful, we strongly encourage installing and running pre-commit locally first to understand its usage.
+
+Finally, most editors have an _autoformat on save_ feature. Consider enabling this option for [black][black-editors]
+and [prettier][prettier-editors].
+
+[black-editors]: https://black.readthedocs.io/en/stable/integrations/editors.html
+[prettier-editors]: https://prettier.io/docs/en/editors.html
+
+## Writing tests
+
+```{note}
+Remember to first install the package with `pip install '-e[dev,test]'`
+```
+
+This package uses the [pytest][] for automated testing. Please [write tests][scanpy-test-docs] for every function added
+to the package.
+
+Most IDEs integrate with pytest and provide a GUI to run tests. Alternatively, you can run all tests from the
+command line by executing
+
+```bash
+pytest
+```
+
+in the root of the repository. Continuous integration will automatically run the tests on all pull requests.
+
+[scanpy-test-docs]: https://scanpy.readthedocs.io/en/latest/dev/testing.html#writing-tests
+
+## Publishing a release
+
+### Updating the version number
+
+Before making a release, you need to update the version number. Please adhere to [Semantic Versioning][semver], in brief
+
+> Given a version number MAJOR.MINOR.PATCH, increment the:
+>
+> 1.  MAJOR version when you make incompatible API changes,
+> 2.  MINOR version when you add functionality in a backwards compatible manner, and
+> 3.  PATCH version when you make backwards compatible bug fixes.
+>
+> Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.
+
+We use [bump2version][] to automatically update the version number in all places and automatically create a git tag.
+Run one of the following commands in the root of the repository
+
+```bash
+bump2version patch
+bump2version minor
+bump2version major
+```
+
+Once you are done, run
+
+```
+git push --tags
+```
+
+to publish the created tag on GitHub.
+
+[bump2version]: https://github.com/c4urself/bump2version
+
+### Building and publishing the package on PyPI
+
+Python packages are not distributed as source code, but as _distributions_. The most common distribution format is the so-called _wheel_. To build a _wheel_, run
+
+```bash
+python -m build
+```
+
+This command creates a _source archive_ and a _wheel_, which are required for publishing your package to [PyPI][]. These files are created directly in the root of the repository.
+
+Before uploading them to [PyPI][] you can check that your _distribution_ is valid by running:
+
+```bash
+twine check dist/*
+```
+
+and finally publishing it with:
+
+```bash
+twine upload dist/*
+```
+
+Provide your username and password when requested and then go check out your package on [PyPI][]!
+
+For more information, follow the [Python packaging tutorial][].
+
+It is possible to automate this with GitHub actions, see also [this feature request][pypi-feature-request]
+in the cookiecutter-scverse template.
+
+[python packaging tutorial]: https://packaging.python.org/en/latest/tutorials/packaging-projects/#generating-distribution-archives
+[pypi-feature-request]: https://github.com/scverse/cookiecutter-scverse/issues/88
+
+## Writing documentation
+
+Please write documentation for new or changed features and use-cases. This project uses [sphinx][] with the following features:
+
+-   the [myst][] extension allows to write documentation in markdown/Markedly Structured Text
+-   [Numpy-style docstrings][numpydoc] (through the [napoloen][numpydoc-napoleon] extension).
+-   Jupyter notebooks as tutorials through [myst-nb][] (See [Tutorials with myst-nb](#tutorials-with-myst-nb-and-jupyter-notebooks))
+-   [Sphinx autodoc typehints][], to automatically reference annotated input and output types
+
+See the [scanpy developer docs](https://scanpy.readthedocs.io/en/latest/dev/documentation.html) for more information
+on how to write documentation.
+
+### Tutorials with myst-nb and jupyter notebooks
+
+The documentation is set-up to render jupyter notebooks stored in the `docs/notebooks` directory using [myst-nb][].
+Currently, only notebooks in `.ipynb` format are supported that will be included with both their input and output cells.
+It is your reponsibility to update and re-run the notebook whenever necessary.
+
+If you are interested in automatically running notebooks as part of the continuous integration, please check
+out [this feature request](https://github.com/scverse/cookiecutter-scverse/issues/40) in the `cookiecutter-scverse`
+repository.
+
+#### Hints
+
+-   If you refer to objects from other packages, please add an entry to `intersphinx_mapping` in `docs/conf.py`. Only
+    if you do so can sphinx automatically create a link to the external documentation.
+-   If building the documentation fails because of a missing link that is outside your control, you can add an entry to
+    the `nitpick_ignore` list in `docs/conf.py`
+
+#### Building the docs locally
+
+```bash
+cd docs
+make html
+open _build/html/index.html
+```
+
+<!-- Links -->
+
+[scanpy developer guide]: https://scanpy.readthedocs.io/en/latest/dev/index.html
+[cookiecutter-scverse-instance]: https://cookiecutter-scverse-instance.readthedocs.io/en/latest/template_usage.html
+[github quickstart guide]: https://docs.github.com/en/get-started/quickstart/create-a-repo?tool=webui
+[codecov]: https://about.codecov.io/sign-up/
+[codecov docs]: https://docs.codecov.com/docs
+[codecov bot]: https://docs.codecov.com/docs/team-bot
+[codecov app]: https://github.com/apps/codecov
+[pre-commit.ci]: https://pre-commit.ci/
+[readthedocs.org]: https://readthedocs.org/
+[myst-nb]: https://myst-nb.readthedocs.io/en/latest/
+[jupytext]: https://jupytext.readthedocs.io/en/latest/
+[pre-commit]: https://pre-commit.com/
+[anndata]: https://github.com/scverse/anndata
+[mudata]: https://github.com/scverse/mudata
+[pytest]: https://docs.pytest.org/
+[semver]: https://semver.org/
+[sphinx]: https://www.sphinx-doc.org/en/master/
+[myst]: https://myst-parser.readthedocs.io/en/latest/intro.html
+[numpydoc-napoleon]: https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html
+[numpydoc]: https://numpydoc.readthedocs.io/en/latest/format.html
+[sphinx autodoc typehints]: https://github.com/tox-dev/sphinx-autodoc-typehints
+[pypi]: https://pypi.org/
diff --git a/docs/developer_docs.md b/docs/developer_docs.md
deleted file mode 100644
index 170109d..0000000
--- a/docs/developer_docs.md
+++ /dev/null
@@ -1,371 +0,0 @@
-# Developer documentation
-
-Welcome to the developer guidelines! This document is split into two parts:
-
-1.  The [repository setup](#setting-up-the-repository). This section is relevant primarily for the repository maintainer and shows how to connect
-    continuous integration services and documents initial set-up of the repository.
-2.  The [contributor guide](#contributing-guide). It contains information relevant to all developers who want to make a contribution.
-
-## Setting up the repository
-
-### Documentation on _readthedocs_
-
-We recommend using [readthedocs.org][] (RTD) to build and host the documentation for your project.
-To enable readthedocs, head over to [their webiste][readthedocs.org] and sign in with your GitHub account.
-On the RTD dashboard choose "Import a Project" and follow the instructions to add your repository.
-
--   Make sure to choose the correct name of the default branch. On GitHub, the default name of the default branch has
-    recently changed from `master` to `main`.
--   We recommend to enable documentation builds for pull requests (PRs). This ensures that a PR doesn't introduce changes
-    that break the documentation. To do so, got to `Admin -> Advanced Settings`, check the
-    `Build pull requests for this projects` option, and click `Save`. For more information, please refer to
-    the [official RTD documentation](https://docs.readthedocs.io/en/stable/pull-requests.html).
--   If you find the RTD builds are failing, you can disable the `fail_on_warning` option in `.readthedocs.yaml`.
-
-### Coverage tests with _Codecov_
-
-Coverage tells what fraction of the code is "covered" by unit tests, thereby encouraging contributors to
-[write tests](#writing-tests).
-To enable coverage checks, head over to [codecov][] and sign in with your GitHub account.
-You'll find more information in "getting started" section of the [codecov docs][].
-
-In brief, you need to:
-
-1. Generate a Codecov Token by clicking _setup repo_ in the codecov dashboard.
-2. Go to the _Settings_ of your newly created repository on GitHub.
-3. Go to _Security > Secrets > Actions_.
-4. Create new repository secret with name `CODECOV_TOKEN` and paste the token generated by codecov
-5. Go back to Github Actions page an re-run previously failed jobs.
-
-### Pre-commit checks
-
-[Pre-commit][] checks are fast programs that
-check code for errors, inconsistencies and code styles, before the code
-is committed.
-
-We recommend setting up [pre-commit.ci][] to enforce consistency checks on every commit
-and pull-request.
-
-To do so, head over to [pre-commit.ci][] and click "Sign In With GitHub". Follow
-the instructions to enable pre-commit.ci for your account or your organization. You
-may choose to enable the service for an entire organization or on a per-repository basis.
-
-Once authorized, pre-commit.ci should automatically be activated.
-
-#### Overview of pre-commit hooks used by the template
-
-The following pre-commit checks are for code style and format:
-
--   [black](https://black.readthedocs.io/en/stable/): standard code
-    formatter in Python.
--   [isort](https://pycqa.github.io/isort/): sort module imports into
-    sections and types.
--   [prettier](https://prettier.io/docs/en/index.html): standard code
-    formatter for non-Python files (e.g. YAML).
--   [blacken-docs](https://github.com/asottile/blacken-docs): black on
-    python code in docs.
-
-The following pre-commit checks are for errors and inconsistencies:
-
--   [flake8](https://flake8.pycqa.org/en/latest/): standard check for errors in Python files.
-    -   [flake8-tidy-imports](https://github.com/adamchainz/flake8-tidy-imports):
-        tidy module imports.
-    -   [flake8-docstrings](https://github.com/PyCQA/flake8-docstrings):
-        pydocstyle extension of flake8.
-    -   [flake8-rst-docstrings](https://github.com/peterjc/e8-rst-docstrings):
-        extension of `flake8-docstrings` for `rst` docs.
-    -   [flake8-comprehensions](https://github.com/adamchainz/e8-comprehensions):
-        write better list/set/dict comprehensions.
-    -   [flake8-bugbear](https://github.com/PyCQA/flake8-bugbear):
-        find possible bugs and design issues in program.
-    -   [flake8-blind-except](https://github.com/elijahandrews/flake8-blind-except):
-        checks for blind, catch-all `except` statements.
--   [yesqa](https://github.com/asottile/yesqa):
-    remove unneccesary `# noqa` comments, follows additional dependencies listed above.
--   [autoflake](https://github.com/PyCQA/autoflake):
-    remove unused imports and variables.
--   [pre-commit-hooks](https://github.com/pre-commit/pre-commit-hooks): generic pre-commit hooks.
-    -   **detect-private-key**: checks for the existence of private keys.
-    -   **check-ast**: check whether files parse as valid python.
-    -   **end-of-file-fixer**:check files end in a newline and only a newline.
-    -   **mixed-line-ending**: checks mixed line ending.
-    -   **trailing-whitespace**: trims trailing whitespace.
-    -   **check-case-conflict**: check files that would conflict with case-insensitive file systems.
--   [pyupgrade](https://github.com/asottile/pyupgrade):
-    upgrade syntax for newer versions of the language.
--   **forbid-to-commit**: Make sure that `*.rej` files cannot be commited. These files are created by the
-    [automated template sync](#automated-template-sync) if there's a merge conflict and need to be addressed manually.
-
-#### Notes on pre-commit checks
-
--   To ignore lint warnigs from **flake8**, see [Ignore certain lint warnings](#ignore-certain-lint-warnings).
--   You can add or remove pre-commit checks by simply deleting relevant lines in the `.pre-commit-config.yaml` file.
-    Some pre-commit checks have additional options that can be specified either in the `pyproject.toml` or tool-specific
-    config files, such as `.prettierrc.yml` for **prettier** and `.flake8` for **flake8**.
-
-### API design
-
-Scverse ecosystem packages should operate on [AnnData][] and/or [MuData][] datastructures and typically use an API
-as originally [introduced by scanpy][scanpy-api] with the following submodules:
-
--   `pp` for preprocessing
--   `tl` for tools (that, compared to `pp` generate interpretable output, often associated with a corresponding plotting
-    function)
--   `pl` for plotting functions
-
-You may add additional submodules as appropriate. While we encourage to follow a scanpy-like API for ecosystem packages,
-there may also be good reasons to choose a different approach, e.g. using an object-oriented API.
-
-[scanpy-api]: https://scanpy.readthedocs.io/en/stable/usage-principles.html
-
-### Ignore certain lint warnings
-
-The [pre-commit checks](#pre-commit-checks) include [flake8](https://flake8.pycqa.org/en/latest/) which checks
-for errors in Python files, including stylistic errors.
-
-In some cases it might overshoot and you may have good reasons to ignore certain warnings.
-
-To ignore an specific error on a per-case basis, you can add a comment `# noqa` to the offending line. You can also
-specify the error ID to ignore, with e.g. `# noqa: E731`. Check the [flake8 guide][] for reference.
-
-Alternatively, you can disable certain error messages for the entire project. To do so, edit the `.flake8`
-file in the root of the repository. Add one line per linting code you wish to ignore and don't forget to add a comment.
-
-```toml
-...
-# line break before a binary operator -> black does not adhere to PEP8
-W503
-# line break occured after a binary operator -> black does not adhere to PEP8
-W504
-...
-```
-
-[flake8 guide]: https://flake8.pycqa.org/en/3.1.1/user/ignoring-errors.html
-
-### Using VCS-based versioning
-
-By default, the template uses hard-coded version numbers that are set in `pyproject.toml` and [managed with
-bump2version](#making-a-release). If you prefer to have your project automatically infer version numbers from git
-tags, it is straightforward to switch to vcs-based versioning using [hatch-vcs][].
-
-In `pyproject.toml` add the following changes, and you are good to go!
-
-```diff
---- a/pyproject.toml
-+++ b/pyproject.toml
-@@ -1,11 +1,11 @@
- [build-system]
- build-backend = "hatchling.build"
--requires = ["hatchling"]
-+requires = ["hatchling", "hatch-vcs"]
-
-
- [project]
- name = "multi-view-atlas"
--version = "0.3.1dev"
-+dynamic = ["version"]
-
-@@ -60,6 +60,9 @@
-+[tool.hatch.version]
-+source = "vcs"
-+
- [tool.coverage.run]
- source = ["multi-view-atlas"]
- omit = [
-```
-
-Don't forget to update the [Making a release section](#making-a-release) in this document accordingly, after you are done!
-
-[hatch-vcs]: https://pypi.org/project/hatch-vcs/
-
-## Contributing guide
-
-Scanpy provides extensive [developer documentation][scanpy developer guide], most of which applies to this repo, too.
-This document will not reproduce the entire content from there. Instead, it aims at summarizing the most important
-information to get you started on contributing.
-
-We assume that you are already familiar with git and with making pull requests on GitHub. If not, please refer
-to the [scanpy developer guide][].
-
-### Installing dev dependencies
-
-In addition to the packages needed to _use_ this package, you need additional python packages to _run tests_ and _build
-the documentation_. It's easy to install them using `pip`:
-
-```bash
-cd multi-view-atlas
-pip install -e ".[dev,test,doc]"
-```
-
-### Code-style
-
-This template uses [pre-commit][] to enforce consistent code-styles. On every commit, pre-commit checks will either
-automatically fix issues with the code, or raise an error message. See [pre-commit checks](#pre-commit-checks) for
-a full list of checks enabled for this repository.
-
-To enable pre-commit locally, simply run
-
-```bash
-pre-commit install
-```
-
-in the root of the repository. Pre-commit will automatically download all dependencies when it is run for the first time.
-
-Alternatively, you can rely on the [pre-commit.ci][] service enabled on GitHub. 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.
-
-If pre-commit.ci added a commit on a branch you still have been working on locally, simply use
-
-```bash
-git pull --rebase
-```
-
-to integrate the changes into yours.
-
-Finally, most editors have an _autoformat on save_ feature. Consider enabling this option for [black][black-editors]
-and [prettier][prettier-editors].
-
-[black-editors]: https://black.readthedocs.io/en/stable/integrations/editors.html
-[prettier-editors]: https://prettier.io/docs/en/editors.html
-
-### Writing tests
-
-This package uses the [pytest][] for automated testing. Please [write tests][scanpy-test-docs] for every function added
-to the package.
-
-Most IDEs integrate with pytest and provide a GUI to run tests. Alternatively, you can run all tests from the
-command line by executing
-
-```bash
-pytest
-```
-
-in the root of the repository. Continuous integration will automatically run the tests on all pull requests.
-
-[scanpy-test-docs]: https://scanpy.readthedocs.io/en/latest/dev/testing.html#writing-tests
-
-### Automated template sync
-
-Automated template sync is enabled by default. This means that every night, a GitHub action runs [cruft][] to check
-if a new version of the `scverse-cookiecutter` template got released. If there are any new changes, a pull request
-proposing these changes is created automatically. This helps keeping the repository up-to-date with the latest
-coding standards.
-
-It may happen that a template sync results in a merge conflict. If this is the case a `*.ref` file with the
-diff is created. You need to manually address these changes and remove the `.rej` file when you are done.
-The pull request can only be merged after all `*.rej` files have been removed.
-
-:::{tip}
-The following hints may be useful to work with the template sync:
-
--   GitHub automatically disables scheduled actions if there has been not activity to the repository for 60 days.
-    You can re-enable or manually trigger the sync by navigating to `Actions` -> `Sync Template` in your GitHub repository.
--   If you want to ignore certain files from the template update, you can add them to the `[tool.cruft]` section in the
-    `pyproject.toml` file in the root of your repository. More details are described in the
-    [cruft documentation][cruft-update-project].
--   To disable the sync entirely, simply remove the file `.github/workflows/sync.yaml`.
-
-:::
-
-[cruft]: https://cruft.github.io/cruft/
-[cruft-update-project]: https://cruft.github.io/cruft/#updating-a-project
-
-### Making a release
-
-#### Updating the version number
-
-Before making a release, you need to update the version number. Please adhere to [Semantic Versioning][semver], in brief
-
-> Given a version number MAJOR.MINOR.PATCH, increment the:
->
-> 1.  MAJOR version when you make incompatible API changes,
-> 2.  MINOR version when you add functionality in a backwards compatible manner, and
-> 3.  PATCH version when you make backwards compatible bug fixes.
->
-> Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.
-
-We use [bump2version][] to automatically update the version number in all places and automatically create a git tag.
-Run one of the following commands in the root of the repository
-
-```bash
-bump2version patch
-bump2version minor
-bump2version major
-```
-
-Once you are done, run
-
-```
-git push --tags
-```
-
-to publish the created tag on GitHub.
-
-[bump2version]: https://github.com/c4urself/bump2version
-
-#### Upload on PyPI
-
-Please follow the [Python packaging tutorial][].
-
-It is possible to automate this with GitHub actions, see also [this feature request][pypi-feature-request]
-in the cookiecutter-scverse template.
-
-[python packaging tutorial]: https://packaging.python.org/en/latest/tutorials/packaging-projects/#generating-distribution-archives
-[pypi-feature-request]: https://github.com/scverse/cookiecutter-scverse/issues/88
-
-### Writing documentation
-
-Please write documentation for your package. This project uses [sphinx][] with the following features:
-
--   the [myst][] extension allows to write documentation in markdown/Markedly Structured Text
--   [Numpy-style docstrings][numpydoc] (through the [napoloen][numpydoc-napoleon] extension).
--   Jupyter notebooks as tutorials through [myst-nb][] (See [Tutorials with myst-nb](#tutorials-with-myst-nb-and-jupyter-notebooks))
--   [Sphinx autodoc typehints][], to automatically reference annotated input and output types
-
-See the [scanpy developer docs](https://scanpy.readthedocs.io/en/latest/dev/documentation.html) for more information
-on how to write documentation.
-
-### Tutorials with myst-nb and jupyter notebooks
-
-The documentation is set-up to render jupyter notebooks stored in the `docs/notebooks` directory using [myst-nb][].
-Currently, only notebooks in `.ipynb` format are supported that will be included with both their input and output cells.
-It is your reponsibility to update and re-run the notebook whenever necessary.
-
-If you are interested in automatically running notebooks as part of the continuous integration, please check
-out [this feature request](https://github.com/scverse/cookiecutter-scverse/issues/40) in the `cookiecutter-scverse`
-repository.
-
-#### Hints
-
--   If you refer to objects from other packages, please add an entry to `intersphinx_mapping` in `docs/conf.py`. Only
-    if you do so can sphinx automatically create a link to the external documentation.
--   If building the documentation fails because of a missing link that is outside your control, you can add an entry to
-    the `nitpick_ignore` list in `docs/conf.py`
-
-#### Building the docs locally
-
-```bash
-cd docs
-make html
-open _build/html/index.html
-```
-
-<!-- Links -->
-
-[scanpy developer guide]: https://scanpy.readthedocs.io/en/latest/dev/index.html
-[codecov]: https://about.codecov.io/sign-up/
-[codecov docs]: https://docs.codecov.com/docs
-[pre-commit.ci]: https://pre-commit.ci/
-[readthedocs.org]: https://readthedocs.org/
-[myst-nb]: https://myst-nb.readthedocs.io/en/latest/
-[jupytext]: https://jupytext.readthedocs.io/en/latest/
-[pre-commit]: https://pre-commit.com/
-[anndata]: https://github.com/scverse/anndata
-[mudata]: https://github.com/scverse/mudata
-[pytest]: https://docs.pytest.org/
-[semver]: https://semver.org/
-[sphinx]: https://www.sphinx-doc.org/en/master/
-[myst]: https://myst-parser.readthedocs.io/en/latest/intro.html
-[numpydoc-napoleon]: https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html
-[numpydoc]: https://numpydoc.readthedocs.io/en/latest/format.html
-[sphinx autodoc typehints]: https://github.com/tox-dev/sphinx-autodoc-typehints
diff --git a/docs/extensions/typed_returns.py b/docs/extensions/typed_returns.py
index 9447813..1135204 100644
--- a/docs/extensions/typed_returns.py
+++ b/docs/extensions/typed_returns.py
@@ -1,24 +1,27 @@
 # code from https://github.com/theislab/scanpy/blob/master/docs/extensions/typed_returns.py
 # with some minor adjustment
+from __future__ import annotations
+
 import re
+from collections.abc import Generator, Iterable
 
 from sphinx.application import Sphinx
 from sphinx.ext.napoleon import NumpyDocstring
 
 
-def _process_return(lines):
+def _process_return(lines: Iterable[str]) -> Generator[str, None, None]:
     for line in lines:
-        m = re.fullmatch(r"(?P<param>\w+)\s+:\s+(?P<type>[\w.]+)", line)
-        if m:
-            # Once this is in scanpydoc, we can use the fancy hover stuff
+        if m := re.fullmatch(r"(?P<param>\w+)\s+:\s+(?P<type>[\w.]+)", line):
             yield f'-{m["param"]} (:class:`~{m["type"]}`)'
         else:
             yield line
 
 
-def _parse_returns_section(self, section):
-    lines_raw = list(_process_return(self._dedent(self._consume_to_next_section())))
-    lines = self._format_block(":returns: ", lines_raw)
+def _parse_returns_section(self: NumpyDocstring, section: str) -> list[str]:
+    lines_raw = self._dedent(self._consume_to_next_section())
+    if lines_raw[0] == ":":
+        del lines_raw[0]
+    lines = self._format_block(":returns: ", list(_process_return(lines_raw)))
     if lines and lines[-1]:
         lines.append("")
     return lines
diff --git a/docs/index.md b/docs/index.md
index 23a1e19..04d594a 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -8,7 +8,8 @@
 
 api.md
 changelog.md
-developer_docs.md
+template_usage.md
+contributing.md
 references.md
 
 notebooks/example
diff --git a/docs/template_usage.md b/docs/template_usage.md
new file mode 100644
index 0000000..ae17161
--- /dev/null
+++ b/docs/template_usage.md
@@ -0,0 +1,364 @@
+# Using this template
+
+Welcome to the developer guidelines! This document is split into two parts:
+
+1.  The [repository setup](#setting-up-the-repository). This section is relevant primarily for the repository maintainer and shows how to connect
+    continuous integration services and documents initial set-up of the repository.
+2.  The [contributor guide](contributing.md#contributing-guide). It contains information relevant to all developers who want to make a contribution.
+
+## Setting up the repository
+
+### First commit
+
+If you are reading this, you should have just completed the repository creation with :
+
+```bash
+cruft create https://github.com/scverse/cookiecutter-scverse
+```
+
+and you should have
+
+```
+cd multi-view-atlas
+```
+
+into the new project directory. Now that you have created a new repository locally, the first step is to push it to github. To do this, you'd have to create a **new repository** on github.
+You can follow the instructions directly on [github quickstart guide][].
+Since `cruft` already populated the local repository of your project with all the necessary files, we suggest to _NOT_ initialize the repository with a `README.md` file or `.gitignore`, because you might encounter git conflicts on your first push.
+If you are familiar with git and knows how to handle git conflicts, you can go ahead with your preferred choice.
+
+:::{note}
+If you are looking at this document in the [cookiecutter-scverse-instance][] repository documentation, throughout this document the name of the project is `cookiecutter-scverse-instance`. Otherwise it should be replaced by your new project name: `multi-view-atlas`.
+:::
+
+Now that your new project repository has been created on github at `https://github.com/emdann/multi-view-atlas` you can push your first commit to github.
+To do this, simply follow the instructions on your github repository page or a more verbose walkthrough here:
+
+Assuming you are in `/your/path/to/multi-view-atlas`. Add all files and commit.
+
+```bash
+# stage all files of your new repo
+git add --all
+# commit
+git commit -m "first commit"
+```
+
+You'll notice that the command `git commit` installed a bunch of packages and triggered their execution: those are pre-commit! To read more about what they are and what they do, you can go to the related section [Pre-commit checks](#pre-commit-checks) in this document.
+
+:::{note}
+There is a chance that `git commit -m "first commit"` fails due to the `prettier` pre-commit formatting the file `.cruft.json`. No problem, you have just experienced what pre-commit checks do in action. Just go ahead and re-add the modified file and try to commit again:
+
+```bash
+ git add -u # update all tracked file
+ git commit -m "first commit"
+```
+
+:::
+
+Now that all the files of the newly created project have been committed, go ahead with the remaining steps:
+
+```bash
+# update the `origin` of your local repo with the remote github link
+git remote add origin https://github.com/emdann/multi-view-atlas.git
+# rename the default branch to main
+git branch -M main
+# push all your files to remote
+git push -u origin main
+```
+
+Your project should be now available at `https://github.com/emdann/multi-view-atlas`. While the repository at this point can be directly used, there are few remaining steps that needs to be done in order to achieve full functionality.
+
+### Coverage tests with _Codecov_
+
+Coverage tells what fraction of the code is "covered" by unit tests, thereby encouraging contributors to
+[write tests](contributing.md#writing-tests).
+To enable coverage checks, head over to [codecov][] and sign in with your GitHub account.
+You'll find more information in "getting started" section of the [codecov docs][].
+
+In the `Actions` tab of your projects' github repository, you can see that the workflows are failing due to the **Upload coverage** step. The error message in the workflow should display something like:
+
+```
+...
+    Retrying 5/5 in 2s..
+    {'detail': ErrorDetail(string='Could not find a repository, try using repo upload token', code='not_found')}
+Error: 404 Client Error: Not Found for url:
+...
+```
+
+While [codecov docs][] has a very extensive documentation on how to get started, _if_ you are using the default settings of this template we can assume that you are using [codecov][] in a github action workflow and hence you can make use of the [codecov bot][].
+
+To set it up, simply go to the [codecov app][] page and follow the instructions to activate it for your repository.
+Once the activation is completed, go back to the `Actions` tab and re-run the failing workflows.
+
+The workflows should now succeed and you will be able to find the code coverage at this link: `https://app.codecov.io/gh/emdann/multi-view-atlas`. You might have to wait couple of minutes and the coverage of this repository should be ~60%.
+
+If your repository is private, you will have to specify an additional token in the repository secrets. In brief, you need to:
+
+1. Generate a Codecov Token by clicking _setup repo_ in the codecov dashboard.
+    - If you have already set up codecov in the repository by following the previous steps, you can directly go to the codecov repo webpage.
+2. Go to _Settings_ and copy **only** the token `_______-____-...`.
+3. Go to _Settings_ of your newly created repository on GitHub.
+4. Go to _Security > Secrets > Actions_.
+5. Create new repository secret with name `CODECOV_TOKEN` and paste the token generated by codecov.
+6. Past these additional lines in `/.github/workflows.test.yaml` under the **Upload coverage** step:
+    ```bash
+    - name: Upload coverage
+      uses: codecov/codecov-action@v3
+      with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+    ```
+7. Go back to github `Actions` page an re-run previously failed jobs.
+
+### Documentation on _readthedocs_
+
+We recommend using [readthedocs.org][] (RTD) to build and host the documentation for your project.
+To enable readthedocs, head over to [their website][readthedocs.org] and sign in with your GitHub account.
+On the RTD dashboard choose "Import a Project" and follow the instructions to add your repository.
+
+-   Make sure to choose the correct name of the default branch. On GitHub, the name of the default branch should be `main` (it has
+    recently changed from `master` to `main`).
+-   We recommend to enable documentation builds for pull requests (PRs). This ensures that a PR doesn't introduce changes
+    that break the documentation. To do so, got to `Admin -> Advanced Settings`, check the
+    `Build pull requests for this projects` option, and click `Save`. For more information, please refer to
+    the [official RTD documentation](https://docs.readthedocs.io/en/stable/pull-requests.html).
+-   If you find the RTD builds are failing, you can disable the `fail_on_warning` option in `.readthedocs.yaml`.
+
+If your project is private, there are ways to enable docs rendering on [readthedocs.org][] but it is more cumbersome and requires a different subscription for read the docs. See a guide [here](https://docs.readthedocs.io/en/stable/guides/importing-private-repositories.html).
+
+### Pre-commit checks
+
+[Pre-commit][] checks are fast programs that
+check code for errors, inconsistencies and code styles, before the code
+is committed.
+
+This template uses a number of pre-commit checks. In this section we'll detail what is used, where they're defined, and how to modify these checks.
+
+#### Pre-commit CI
+
+We recommend setting up [pre-commit.ci][] to enforce consistency checks on every commit
+and pull-request.
+
+To do so, head over to [pre-commit.ci][] and click "Sign In With GitHub". Follow
+the instructions to enable pre-commit.ci for your account or your organization. You
+may choose to enable the service for an entire organization or on a per-repository basis.
+
+Once authorized, pre-commit.ci should automatically be activated.
+
+#### Overview of pre-commit hooks used by the template
+
+The following pre-commit hooks are for code style and format:
+
+-   [black](https://black.readthedocs.io/en/stable/):
+    standard code formatter in Python.
+-   [blacken-docs](https://github.com/asottile/blacken-docs):
+    black on Python code in docs.
+-   [prettier](https://prettier.io/docs/en/index.html):
+    standard code formatter for non-Python files (e.g. YAML).
+-   [ruff][] based checks:
+    -   [isort](https://beta.ruff.rs/docs/rules/#isort-i) (rule category: `I`):
+        sort module imports into sections and types.
+    -   [pydocstyle](https://beta.ruff.rs/docs/rules/#pydocstyle-d) (rule category: `D`):
+        pydocstyle extension of flake8.
+    -   [flake8-tidy-imports](https://beta.ruff.rs/docs/rules/#flake8-tidy-imports-tid) (rule category: `TID`):
+        tidy module imports.
+    -   [flake8-comprehensions](https://beta.ruff.rs/docs/rules/#flake8-comprehensions-c4) (rule category: `C4`):
+        write better list/set/dict comprehensions.
+    -   [pyupgrade](https://beta.ruff.rs/docs/rules/#pyupgrade-up) (rule category: `UP`):
+        upgrade syntax for newer versions of the language.
+
+The following pre-commit hooks are for errors and inconsistencies:
+
+-   [pre-commit-hooks](https://github.com/pre-commit/pre-commit-hooks): generic pre-commit hooks for text files.
+    -   **detect-private-key**: checks for the existence of private keys.
+    -   **check-ast**: check whether files parse as valid python.
+    -   **end-of-file-fixer**: check files end in a newline and only a newline.
+    -   **mixed-line-ending**: checks mixed line ending.
+    -   **trailing-whitespace**: trims trailing whitespace.
+    -   **check-case-conflict**: check files that would conflict with case-insensitive file systems.
+    -   **forbid-to-commit**: Make sure that `*.rej` files cannot be commited.
+        These files are created by the [automated template sync](#automated-template-sync)
+        if there's a merge conflict and need to be addressed manually.
+-   [ruff][] based checks:
+    -   [pyflakes](https://beta.ruff.rs/docs/rules/#pyflakes-f) (rule category: `F`):
+        various checks for errors.
+    -   [pycodestyle](https://beta.ruff.rs/docs/rules/#pycodestyle-e-w) (rule category: `E`, `W`):
+        various checks for errors.
+    -   [flake8-bugbear](https://beta.ruff.rs/docs/rules/#flake8-bugbear-b) (rule category: `B`):
+        find possible bugs and design issues in program.
+    -   [flake8-blind-except](https://beta.ruff.rs/docs/rules/#flake8-blind-except-ble) (rule category: `BLE`):
+        checks for blind, catch-all `except` statements.
+    -   [Ruff-specific rules](https://beta.ruff.rs/docs/rules/#ruff-specific-rules-ruf) (rule category: `RUF`):
+        -   `RUF100`: remove unneccesary `# noqa` comments ()
+
+#### How to add or remove pre-commit checks
+
+The [pre-commit checks](#pre-commit-checks) check for both correctness and stylistic errors.
+In some cases it might overshoot and you may have good reasons to ignore certain warnings.
+This section shows you where these checks are defined, and how to enable/ disable them.
+
+##### pre-commit
+
+You can add or remove pre-commit checks by simply deleting relevant lines in the `.pre-commit-config.yaml` file under the repository root.
+Some pre-commit checks have additional options that can be specified either in the `pyproject.toml` (for `ruff` and `black`) or tool-specific
+config files, such as `.prettierrc.yml` for **prettier**.
+
+##### Ruff
+
+This template configures `ruff` through the `[tool.ruff]` entry in the `pyproject.toml`.
+For further information `ruff` configuration, see [the docs](https://beta.ruff.rs/docs/configuration/).
+
+Ruff assigns code to the rules it checks (e.g. `E401`) and groups them under a rule category (e.g. `E`).
+Rule categories are selectively enabled by including them under the `select` key:
+
+```toml
+[tool.ruff]
+...
+
+select = [
+    "F",  # Errors detected by Pyflakes
+    "E",  # Error detected by Pycodestyle
+    "W",  # Warning detected by Pycodestyle
+    "I",  # isort
+    ...
+]
+```
+
+The `ignore` entry is used to disable specific rules for the entire project.
+Add the rule code(s) you want to ignore and don't forget to add a comment explaining why.
+You can find a long list of checks that this template disables by default sitting there already.
+
+```toml
+ignore = [
+    ...
+    # __magic__ methods are are often self-explanatory, allow missing docstrings
+    "D105",
+    ...
+]
+```
+
+Checks can be ignored per-file (or glob pattern) with `[tool.ruff.per-file-ignores]`.
+
+```toml
+[tool.ruff.per-file-ignores]
+"docs/*" = ["I"]
+"tests/*" = ["D"]
+"*/__init__.py" = ["F401"]
+```
+
+To ignore a specific rule on a per-case basis, you can add a `# noqa: <rule>[, <rule>, …]` comment to the offending line.
+Specify the rule code(s) to ignore, with e.g. `# noqa: E731`. Check the [Ruff guide][] for reference.
+
+```{note}
+The `RUF100` check will remove rule codes that are no longer necessary from `noqa` comments.
+If you want to add a code that comes from a tool other than Ruff,
+add it to Ruff’s [`external = [...]`](https://beta.ruff.rs/docs/settings/#external) setting to prevent `RUF100` from removing it.
+```
+
+[ruff]: https://beta.ruff.rs/docs/
+[ruff guide]: https://beta.ruff.rs/docs/configuration/#suppressing-errors
+
+### API design
+
+Scverse ecosystem packages should operate on [AnnData][] and/or [MuData][] data structures and typically use an API
+as originally [introduced by scanpy][scanpy-api] with the following submodules:
+
+-   `pp` for preprocessing
+-   `tl` for tools (that, compared to `pp` generate interpretable output, often associated with a corresponding plotting
+    function)
+-   `pl` for plotting functions
+
+You may add additional submodules as appropriate. While we encourage to follow a scanpy-like API for ecosystem packages,
+there may also be good reasons to choose a different approach, e.g. using an object-oriented API.
+
+[scanpy-api]: https://scanpy.readthedocs.io/en/stable/usage-principles.html
+
+### Using VCS-based versioning
+
+By default, the template uses hard-coded version numbers that are set in `pyproject.toml` and [managed with
+bump2version](contributing.md#publishing-a-release). If you prefer to have your project automatically infer version numbers from git
+tags, it is straightforward to switch to vcs-based versioning using [hatch-vcs][].
+
+In `pyproject.toml` add the following changes, and you are good to go!
+
+```diff
+--- a/pyproject.toml
++++ b/pyproject.toml
+@@ -1,11 +1,11 @@
+ [build-system]
+ build-backend = "hatchling.build"
+-requires = ["hatchling"]
++requires = ["hatchling", "hatch-vcs"]
+
+
+ [project]
+ name = "multi-view-atlas"
+-version = "0.3.1dev"
++dynamic = ["version"]
+
+@@ -60,6 +60,9 @@
++[tool.hatch.version]
++source = "vcs"
++
+ [tool.coverage.run]
+ source = ["multi-view-atlas"]
+ omit = [
+```
+
+Don't forget to update the [Making a release section](contributing.md#publishing-a-release) in this document accordingly, after you are done!
+
+[hatch-vcs]: https://pypi.org/project/hatch-vcs/
+
+### Automated template sync
+
+Automated template sync is enabled by default. This means that every night, a GitHub action runs [cruft][] to check
+if a new version of the `scverse-cookiecutter` template got released. If there are any new changes, a pull request
+proposing these changes is created automatically. This helps keeping the repository up-to-date with the latest
+coding standards.
+
+It may happen that a template sync results in a merge conflict. If this is the case a `*.ref` file with the
+diff is created. You need to manually address these changes and remove the `.rej` file when you are done.
+The pull request can only be merged after all `*.rej` files have been removed.
+
+:::{tip}
+The following hints may be useful to work with the template sync:
+
+-   GitHub automatically disables scheduled actions if there has been not activity to the repository for 60 days.
+    You can re-enable or manually trigger the sync by navigating to `Actions` -> `Sync Template` in your GitHub repository.
+-   If you want to ignore certain files from the template update, you can add them to the `[tool.cruft]` section in the
+    `pyproject.toml` file in the root of your repository. More details are described in the
+    [cruft documentation][cruft-update-project].
+-   To disable the sync entirely, simply remove the file `.github/workflows/sync.yaml`.
+
+:::
+
+[cruft]: https://cruft.github.io/cruft/
+[cruft-update-project]: https://cruft.github.io/cruft/#updating-a-project
+
+## Moving forward
+
+You have reached the end of this document. Congratulations! You have successfully set up your project and are ready to start.
+For everything else related to documentation, code style, testing and publishing your project ot pypi, please refer to the [contributing docs](contributing.md#contributing-guide).
+
+<!-- Links -->
+
+[scanpy developer guide]: https://scanpy.readthedocs.io/en/latest/dev/index.html
+[cookiecutter-scverse-instance]: https://cookiecutter-scverse-instance.readthedocs.io/en/latest/template_usage.html
+[github quickstart guide]: https://docs.github.com/en/get-started/quickstart/create-a-repo?tool=webui
+[codecov]: https://about.codecov.io/sign-up/
+[codecov docs]: https://docs.codecov.com/docs
+[codecov bot]: https://docs.codecov.com/docs/team-bot
+[codecov app]: https://github.com/apps/codecov
+[pre-commit.ci]: https://pre-commit.ci/
+[readthedocs.org]: https://readthedocs.org/
+[myst-nb]: https://myst-nb.readthedocs.io/en/latest/
+[jupytext]: https://jupytext.readthedocs.io/en/latest/
+[pre-commit]: https://pre-commit.com/
+[anndata]: https://github.com/scverse/anndata
+[mudata]: https://github.com/scverse/mudata
+[pytest]: https://docs.pytest.org/
+[semver]: https://semver.org/
+[sphinx]: https://www.sphinx-doc.org/en/master/
+[myst]: https://myst-parser.readthedocs.io/en/latest/intro.html
+[numpydoc-napoleon]: https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html
+[numpydoc]: https://numpydoc.readthedocs.io/en/latest/format.html
+[sphinx autodoc typehints]: https://github.com/tox-dev/sphinx-autodoc-typehints
diff --git a/pyproject.toml b/pyproject.toml
index 95a990d..972782f 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -33,11 +33,12 @@ dependencies = [
 dev = [
     # CLI for bumping the version number
     "bump2version",
-    "pre-commit"
+    "pre-commit",
+    "twine>=4.0.2"
 ]
 doc = [
     "sphinx>=4",
-    "sphinx-book-theme>=0.3.3",
+    "sphinx-book-theme>=1.0.0",
     "myst-nb",
     "sphinxcontrib-bibtex>=1.0.0",
     "sphinx-autodoc-typehints",
@@ -64,32 +65,59 @@ addopts = [
     "--import-mode=importlib",  # allow using test files with same name
 ]
 
-[tool.isort]
-include_trailing_comma = true
-multi_line_output = 3
-profile = "black"
-skip_glob = ["docs/*"]
-
 [tool.black]
 line-length = 120
-target-version = ['py38']
-include = '\.pyi?$'
-exclude = '''
-(
-  /(
-      \.eggs
-    | \.git
-    | \.hg
-    | \.mypy_cache
-    | \.tox
-    | \.venv
-    | _build
-    | buck-out
-    | build
-    | dist
-  )/
-)
-'''
+target-version = ["py38"]
+
+[tool.ruff]
+src = ["src"]
+line-length = 120
+target-version = "py38"
+select = [
+    "F",  # Errors detected by Pyflakes
+    "E",  # Error detected by Pycodestyle
+    "W",  # Warning detected by Pycodestyle
+    "I",  # isort
+    "D",  # pydocstyle
+    "B",  # flake8-bugbear
+    "TID",  # flake8-tidy-imports
+    "C4",  # flake8-comprehensions
+    "BLE",  # flake8-blind-except
+    "UP",  # pyupgrade
+    "RUF100",  # Report unused noqa directives
+]
+ignore = [
+    # line too long -> we accept long comment lines; black gets rid of long code lines
+    "E501",
+    # Do not assign a lambda expression, use a def -> lambda expression assignments are convenient
+    "E731",
+    # allow I, O, l as variable names -> I is the identity matrix
+    "E741",
+    # Missing docstring in public package
+    "D104",
+    # Missing docstring in public module
+    "D100",
+    # Missing docstring in __init__
+    "D107",
+    # Errors from function calls in argument defaults. These are fine when the result is immutable.
+    "B008",
+    # __magic__ methods are are often self-explanatory, allow missing docstrings
+    "D105",
+    # first line should end with a period [Bug: doesn't work with single-line docstrings]
+    "D400",
+    # First line should be in imperative mood; try rephrasing
+    "D401",
+    ## Disable one in each pair of mutually incompatible rules
+    # We don’t want a blank line before a class docstring
+    "D203",
+    # We want docstrings to start immediately after the opening triple quote
+    "D213",
+]
+
+[tool.ruff.per-file-ignores]
+"docs/*" = ["I"]
+"tests/*" = ["D"]
+"*/__init__.py" = ["F401"]
 
 [tool.jupytext]
 formats = "ipynb,md"
diff --git a/pyproject.toml.rej b/pyproject.toml.rej
new file mode 100644
index 0000000..5f0501f
--- /dev/null
+++ b/pyproject.toml.rej
@@ -0,0 +1,9 @@
+diff a/pyproject.toml b/pyproject.toml	(rejected hunks)
+@@ -2,7 +2,6 @@
+ build-backend = "hatchling.build"
+ requires = ["hatchling"]
+ 
+-
+ [project]
+ name = "multi-view-atlas"
+ version = "0.0.1"