Deploy preview for PR 98 🛫

pr-preview/pr-98/.buildinfo

@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file records the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: 2dae33ee9e31c6a8e628e9802051a834
+tags: 645f666f9bcd5a90fca523b33c5a78b7

pr-preview/pr-98/_sources/CHANGELOG.md

@@ -0,0 +1,3 @@
+```{include} ../CHANGELOG.md
+
+```

pr-preview/pr-98/_sources/cli_command_reference.md

@@ -0,0 +1,97 @@
+# Command reference
+
+## dso
+
+```{eval-rst}
+.. click:run::
+    from dso.cli import dso
+    invoke(dso, args=["--help"])
+```
+
+## dso compile-config
+
+```{eval-rst}
+.. click:run::
+    from dso.cli import dso
+    invoke(dso, args=["compile-config", "--help"])
+```
+
+## dso create
+
+```{eval-rst}
+.. click:run::
+    from dso.cli import dso
+    invoke(dso, args=["create", "--help"])
+```
+
+### dso create folder
+
+```{eval-rst}
+.. click:run::
+    from dso.cli import dso
+    invoke(dso, args=["create", "folder", "--help"])
+```
+
+### dso create stage
+
+```{eval-rst}
+.. click:run::
+    from dso.cli import dso
+    invoke(dso, args=["create", "stage", "--help"])
+```
+
+## dso exec
+
+```{eval-rst}
+.. click:run::
+    from dso.cli import dso
+    invoke(dso, args=["exec", "--help"])
+```
+
+### dso exec quarto
+
+```{eval-rst}
+.. click:run::
+    from dso.cli import dso
+    invoke(dso, args=["exec", "quarto" ,"--help"])
+```
+
+## dso get-config
+
+```{eval-rst}
+.. click:run::
+    from dso.cli import dso
+    invoke(dso, args=["get-config", "--help"])
+```
+
+## dso init
+
+```{eval-rst}
+.. click:run::
+    from dso.cli import dso
+    invoke(dso, args=["init", "--help"])
+```
+
+## dso lint
+
+```{eval-rst}
+.. click:run::
+    from dso.cli import dso
+    invoke(dso, args=["lint", "--help"])
+```
+
+## dso repro
+
+```{eval-rst}
+.. click:run::
+    from dso.cli import dso
+    invoke(dso, args=["repro", "--help"])
+```
+
+## dso watermark
+
+```{eval-rst}
+.. click:run::
+    from dso.cli import dso
+    invoke(dso, args=["watermark", "--help"])
+```

pr-preview/pr-98/_sources/cli_configuration.md

@@ -0,0 +1,39 @@
+# Configuration
+
+This section provides and overview of dso settings and how to apply them.
+Please refer to [DVC configuration](https://dvc.org/doc/user-guide/project-structure/configuration#dvc-configuration) for dvc settings.
+
+## Environment variables
+
+The following environment variables can be used to change certain dso behaviors, independent of the project.
+
+| variable                        | purpose                                                                                                                                           |
+| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `DSO_SKIP_CHECK_ASK_PRE_COMMIT` | If set to any non-empty value, dso does not ask whether to install the pre-commit hooks for in a project.                                         |
+| `DSO_QUIET`                     | `DSO_QUIET=1` disables info messages, `DSO_QUIET=2` disables warnings. This is equivalent to `-q` and `-qq`, respectively.                        |
+| `DSO_VERBOSE`                   | `DSO_VERBOSE=1` enables debug logging. This is equivalent to `-v`                                                                                 |
+| `DSO_SKIP_COMPILE`              | `DSO_SKIP_COMPILE` disables automated internal calls to `dso compile-config` in commands that support it. This is equivalent to `--skip-compile`. |
+
+## Project-specific settings -- `pyproject.toml`
+
+Project-specific dso settings can be set in the `pyproject.toml` file at the root of each project in the
+`[tool.dso]` section. As the `pyproject.toml` file is tracked by git, these changes affect all users who
+collaborate on the project.
+
+```toml
+[tool.dso]
+# whether to compile relative paths declared with `!path` into absolute paths or
+# relative paths (relative to each stage). Defaults to `true`.
+use_relative_path = true
+```
+
+## Project and user specific settings -- `.dso.json`
+
+For project-specific settings that are not intended to be shared across collaborators. This file is stored
+at the root of each project. It is not meant to be edited by hand, but will be created and modified by the `dso` CLI as appropriate.
+
+It currently tracks the following properties:
+
+| variable               | purpose                                                                                                                        |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `check_ask_pre_commit` | If the user answered "no" to the question if they want to install pre-commit hooks in this project, this will be tracked here. |

pr-preview/pr-98/_sources/cli_installation.md

@@ -0,0 +1,63 @@
+# Installation
+
+The DSO CLI is available [from PyPI](https://pypi.org/project/dso-core/). The package is named `dso-core`
+You can think of it as the "core" package of DSO, while there is also a [separate R package](https://github.com/Boehringer-Ingelheim/dso-r)
+and there might be other "extension" packages in the future.
+
+We recommend installing the DSO CLI in an isolated environment using, e.g., [uv](https://docs.astral.sh/uv/) or [pipx](https://pipx.pypa.io/latest/installation/).
+
+```bash
+uv tool install dso-core
+```
+
+This command installs the `dso` binary:
+
+```{eval-rst}
+.. click:run::
+    from dso.cli import dso
+    invoke(dso, args=["--version"])
+```
+
+If you prefer to manage the Python environment yourself, you can use `pip` as usual:
+
+```bash
+pip install dso-core
+```
+
+## Freezing the dso version within a project
+
+:::{attention}
+
+This feature is still experimental. In particular, we are still working on the ergonomics,
+as remembering to type `uv run dso` every time is not very user-friendly. Once this is
+worked out, it will very likely become the default for all dso projects.
+
+See also [dso#3](https://github.com/Boehringer-Ingelheim/dso-mgr/issues/3).
+:::
+
+To ensure consistent results between collaborators and that the porject can be reproduced in exactly the
+same way in the future, it is good practice to pin a specific version of dso within each project. Since
+each dso project is also a [uv project](https://docs.astral.sh/uv/guides/projects/) with dependencies
+declared in `pyproject.toml`, this makes it easy freeze the dso version.
+
+By using
+
+```bash
+uv run dso
+```
+
+instead of
+
+```bash
+dso
+```
+
+`uv` runs the specified version of `dso` and installes it automatically in the background, if necessary. Running
+this command for the first time will create a [`uv.lock`](https://docs.astral.sh/uv/guides/projects/#uvlock) file that
+contains the exact information about the project's dependencies.
+
+To update the version of `dso` within the project, you can use
+
+```bash
+uv add -U dso_core
+```

pr-preview/pr-98/_sources/contributing.md

@@ -0,0 +1,153 @@
+# Contributing guide
+
+We assume that you are already familiar with git and with making pull requests on GitHub.
+
+## Installing dev dependencies
+
+In addition to the packages needed to _use_ this package,
+you need additional python packages to [run tests](#writing-tests) and [build the documentation](#docs-building).
+
+The easiest way is to get familiar with [hatch environments][], with which these tasks are simply:
+
+```bash
+hatch test  # defined in the table [tool.hatch.envs.hatch-test] in pyproject.toml
+hatch run docs:build  # defined in the table [tool.hatch.envs.docs]
+```
+
+If you prefer managing environments manually, you can use `pip`:
+
+```bash
+cd dso
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev,test,doc]"
+```
+
+[hatch environments]: https://hatch.pypa.io/latest/tutorials/environment/basic-usage/
+
+## Code-style
+
+This package 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.
+
+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 [ruff][ruff-editors] and [prettier][prettier-editors].
+
+[pre-commit]: https://pre-commit.com/
+[pre-commit.ci]: https://pre-commit.ci/
+[ruff-editors]: https://docs.astral.sh/ruff/integrations/
+
+[prettier-editors]: https://prettier.io/docs/en/editors.html
+
+(writing-tests)=
+
+## Writing tests
+
+This package uses [pytest][] for automated testing.
+Please write {doc}`scanpy:dev/testing` for every function added to the package.
+
+Most IDEs integrate with pytest and provide a GUI to run tests.
+Just point yours to one of the environments returned by
+
+```bash
+hatch env create hatch-test  # create test environments for all supported versions
+hatch env find hatch-test  # list all possible test environment paths
+```
+
+Alternatively, you can run all tests from the command line by executing
+
+```bash
+hatch test  # test with the highest supported Python version
+# or
+hatch test --all  # test with all supported Python versions
+```
+
+in the root of the repository.
+
+[pytest]: https://docs.pytest.org/
+
+### Continuous integration
+
+Continuous integration will automatically run the tests on all pull requests and test
+against the minimum and maximum supported Python version.
+
+Additionally, there's a CI job that tests against pre-releases of all dependencies (if there are any).
+The purpose of this check is to detect incompatibilities of new package versions early on and
+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.
+
+## Publishing a release
+
+### Updating the version number
+
+DSO uses [hatch-vcs](https://github.com/ofek/hatch-vcs) to automaticlly retrieve the version number
+from the git tag. To make a new release, navigate to the “Releases” page of this project on GitHub. Specify vX.X.X as a tag name and create a release. For more information, see [managing GitHub releases][]. This will automatically create a git tag and trigger a Github workflow that creates a release on PyPI.
+
+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.
+
+[semver]: https://semver.org/
+[managing GitHub releases]: https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository
+[pypi]: https://pypi.org/
+
+## 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).
+-   [sphinx-autodoc-typehints][], to automatically reference annotated input and output types
+-   Citations can be included with [sphinxcontrib-bibtex](https://sphinxcontrib-bibtex.readthedocs.io/)
+
+See scanpy’s {doc}`scanpy:dev/documentation` for more information on how to write your own.
+
+[sphinx]: https://www.sphinx-doc.org/en/master/
+[myst]: https://myst-parser.readthedocs.io/en/latest/intro.html
+[myst-nb]: https://myst-nb.readthedocs.io/en/latest/
+[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
+
+### 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`
+
+(docs-building)=
+
+### Building the docs locally
+
+```bash
+hatch docs:build
+hatch docs:open
+```

pr-preview/pr-98/_sources/faq.md

@@ -0,0 +1,5 @@
+# FAQ
+
+## Can I use dvc to track files that are outside the repository?
+
+Yes, this is possible by specifying an absolute path to that file. However, note that DVC will only _track_ but not _version_ that file. I.e. updating that files will invalidate the cache for `dvc repro`, but it will not be updated by `dvc pull` / `dvc checkout`.