docs: update installation (#87)

* Update installation

* Update example output

* docs: configuration

* Fix typos

* fix xref

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.
 

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.
 
-| <img src="img/dso_kraken.jpg" alt="DSO Kraken" width="700"> | <img src="img/dso_tools.png" alt="tools used by DSO"> |
-| ----------------------------------------------------------- | ----------------------------------------------------- |
+<!-- use absolute URL to make this work also on PyPI -->
+
+| <img src="https://raw.githubusercontent.com/Boehringer-Ingelheim/dso/refs/heads/main/img/dso_kraken.jpg" alt="DSO Kraken" width="700"> | <img src="https://raw.githubusercontent.com/Boehringer-Ingelheim/dso/refs/heads/main/img/dso_tools.png" alt="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
 

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. |

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
+```

docs/index.md

@@ -38,4 +38,5 @@ python_api.md
 
 Usage <https://boehringer-ingelheim.github.io/dso-r/>
 API reference <https://boehringer-ingelheim.github.io/dso-r/reference/index.html>
+Changelog <https://github.com/Boehringer-Ingelheim/dso-r/blob/main/CHANGELOG.md>
 ```

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.
 

src/dso/templates/init/default/.gitignore

@@ -1,5 +1,5 @@
 # dso
-.dso.jso
+.dso.json
 params.yaml
 
 # uv