From b79814b6a6c41d579f82b2aee4502ec81eee4732 Mon Sep 17 00:00:00 2001 From: Gregor Sturm Date: Thu, 23 Jan 2025 17:06:50 +0100 Subject: [PATCH] docs: update installation (#87) * Update installation * Update example output * docs: configuration * Fix typos * fix xref --- CHANGELOG.md | 8 ++- README.md | 10 ++-- docs/cli_configuration.md | 32 ++++++++++-- docs/cli_installation.md | 62 ++++++++++++++++++++++- docs/index.md | 1 + docs/python_usage.md | 2 +- src/dso/templates/init/default/.gitignore | 2 +- 7 files changed, 105 insertions(+), 12 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 2dbd90a..85c6ba3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,6 +10,12 @@ and this project adheres to [Semantic Versioning][]. ## [Unreleased] +### Documentation + +- Various documentation updates, working towards the first public version of the docs. + +## v0.11.0 + ### Template updates - Single `.gitignore` file per stage. Content of input/output/report folders is ignored. These folders @@ -28,7 +34,7 @@ and this project adheres to [Semantic Versioning][]. - `dso exec quarto` automatically creates an `output` directory in the stage if it doesn't exist. If it doesn't contain any file, it will be removed again after completion ([#73](https://github.com/Boehringer-Ingelheim/dso/pull/73)). -## Documentation +### Documentation - Various documentation updates, working towards the first public version of the docs. diff --git a/README.md b/README.md index 6109dfe..4fbbc2d 100644 --- a/README.md +++ b/README.md @@ -7,16 +7,18 @@ templates, dependency management via [uv](https://docs.astral.sh/uv), linting ch At Boehringer Ingelheim, we introduced DSO to meet the high quality standards required for biomarker analysis in clinical trials. DSO is under active development and we value community feedback. -| DSO Kraken | tools used by DSO | -| ----------------------------------------------------------- | ----------------------------------------------------- | + + +| DSO Kraken | tools used by DSO | +| -------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | ## Getting started -Please refer to the documentation, in particular ... +Please refer to the [documentation](https://boehringer-ingelheim.github.io/dso), in particular the [getting started](https://boehringer-ingelheim.github.io/dso/getting_started.html) section. ## Installation -TODO +See [installation](https://boehringer-ingelheim.github.io/dso/cli_installation.html). ## Contact diff --git a/docs/cli_configuration.md b/docs/cli_configuration.md index f022077..3fd4d10 100644 --- a/docs/cli_configuration.md +++ b/docs/cli_configuration.md @@ -1,15 +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. -## pyproject.toml +## 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: +`[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). -# default is `true` +# 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. | diff --git a/docs/cli_installation.md b/docs/cli_installation.md index 7cd4222..a863e6c 100644 --- a/docs/cli_installation.md +++ b/docs/cli_installation.md @@ -1,3 +1,63 @@ # Installation -TODO +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 +``` diff --git a/docs/index.md b/docs/index.md index c73062d..8f934c2 100644 --- a/docs/index.md +++ b/docs/index.md @@ -38,4 +38,5 @@ python_api.md Usage API reference +Changelog ``` diff --git a/docs/python_usage.md b/docs/python_usage.md index 1396004..ad1dcb2 100644 --- a/docs/python_usage.md +++ b/docs/python_usage.md @@ -19,7 +19,7 @@ from dso import read_params params = read_params("subfolder/my_stage") ``` -By default, DSO compiles paths in configuration files to paths relative to each stage (see [configuration](cli_configuration.md#pyprojecttoml)). +By default, DSO compiles paths in configuration files to paths relative to each stage (see [configuration](cli_configuration.md#project-specific-settings----pyprojecttoml)). From Python, you can use {func}`~dso.stage_here` to resolve paths relative to the current stage independent of your current working directory, e.g. diff --git a/src/dso/templates/init/default/.gitignore b/src/dso/templates/init/default/.gitignore index cb2e7c0..33d88be 100644 --- a/src/dso/templates/init/default/.gitignore +++ b/src/dso/templates/init/default/.gitignore @@ -1,5 +1,5 @@ # dso -.dso.jso +.dso.json params.yaml # uv