Screenshots with rich-codex

.github/workflows/screenshots.yml

@@ -0,0 +1,33 @@
+name: Docs screenshots
+on:
+  workflow_dispatch:
+  pull_request:
+
+jobs:
+  rich_codex:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out DSO code
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.head_ref }}
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: "pip"
+
+      - name: Install DSO
+        run: pip install .
+
+      - name: Generate terminal images with rich-codex
+        uses: ewels/rich-codex@v1
+        with:
+          clean_img_paths: docs/images/screenshots/*.svg
+          commit_changes: false
+          skip_git_checks: true
+
+      - uses: stefanzweifel/git-auto-commit-action@v5
+        with:
+          commit_message: Rich codex
+          file_pattern: "docs/*.png"

README.md

@@ -1,6 +1,6 @@
 # DSO: data science operations
 
-<img src="img/dso_kraken.jpg" alt="DSO Kraken" width="250" />
+<img src="docs/img/dso_kraken.jpg" alt="DSO Kraken" width="250" />
 
 *DSO* is a command line helper for building reproducible data anlaysis projects with ease.
 It builds on top of [dvc](https://github.com/iterative/dvc) for data versioning and provides project
@@ -21,22 +21,14 @@ step of your analysis (usually one script with defined inputs and outputs) organ
 cannot be nested. A *folder* is used to organize stages in a hierarchical way within the project.
 
 You can use `dso init` to create a new project
-```
-$> dso init
-Please enter the name of the project, e.g. "single_cell_lung_atlas": my_cool_project
-Please add a short description of the project: This analysis solves *all* the problems!
-```
+
+![`dso init "my_cool_project"`](docs/img/dso_init.png)
 
 Within a project, you can use `dso create` to initalize folders and stages from a predefined template
 
-```
-$> dso create stage
-? Choose a template: (Use arrow keys)
-   bash
- » quarto
-Please enter the name of the stage, e.g. "01_preprocessing": 02_quality_control
-Please add a short description of the stage: Make a PCA to detect outliers
-```
+![`dso create stage --template bash --description 'Quality control'`](docs/img/dso_stage.png)
+
+All of the above is also possible in an interactively guided text based way if you do not supply the parameters directly.
 
 ### How-to write and use config files
 The config files in a project, subfolder or stage are the cornerstone of any reproducable analysis by minimising analysis configuration errors within related scripts. Additionally, config files reduce the time needed to modify your scripts when changing configurations such as p-value cutoffs, excluded samples, output directory, data input, and many more.
@@ -45,42 +37,31 @@ A config file of a project, subfolder, or stage contains all necessary parameter
 
 In DSO two parameter files are given called `params.yaml` and `params.in.yaml`. `params.yaml` is an autogenerated YAML containing all the parameters specified in the params.in.yaml and other params.yaml files in its parent directories (see figure below for an example how this behaves in real). `params.yaml` will be compiled when running `dso compile-config`.
 
-<img src="img/config.png" width="500" alt="Hierarchical configuration schema" />
+<img src="docs/img/config.png" width="500" alt="Hierarchical configuration schema" />
 
-```
-$> dso compile-config
-[08/22/24 20:53:43] INFO     Detected /home/grst/my_cool_project as project root.
-                    INFO     Compiling a total of 2 config files.
-                    INFO     Configuration compiled successfully.
-```
+![`dso init "my_cool_project" --description "test" && cd my_cool_project && dso compile-config`](docs/img/dso_compile_config.png)
 
 ### Linting checks
 
 Dso provides linting checks that detect common errors in analysis projects. Right now only few checks are implemented,
 but more will be available in the future.
 
-To run the linting checks manuall, execute
+To run the linting checks manuall, execute `dso lint`:
 
-```
-$> dso lint
-[08/22/24 20:53:43] INFO     Compiled a list of 22 to be linted
-```
+![`dso init "my_cool_project" --description "test" && cd my_cool_project && dso lint`](docs/img/dso_lint.png)
 
 However, it is preferable to execute linting checks as pre-commit hooks and/or as continuous integration checks.
 A `.pre-commit-config.yaml` comes with the DSO project template. Simply activate it using `pre-commit install`.
 
 ### Reproducing projects
 
-To reproduce/execute all stages within a project, run
+To reproduce/execute all stages within a project, run `dso repro`
 
-```
-$> dso repro
-```
+![`dso init "my_cool_project" --description "test" && cd my_cool_project && dso repro`](docs/img/dso_repro.png)
 
 This is a thin wrapper around `dvc repro` that compiles all configuration files beforehand.
 DVC will only reproduce stages defined in the dvc.yaml where changes have been made. When dependencies have been changed, previous stages will also be re-run.
 
-
 ### Integration with quarto
 
 DSO provides some additional tooling around quarto documents for generating reproducible reports. When you create a
@@ -112,7 +93,6 @@ To access stage parameters and resolve file paths relative to the stage director
 companion package [`dso-r`](https://github.com/Boehringer-Ingelheim/dso-r) that provides the two functions
 `read_params(stage_name)` and `stage_here(path)`.
 
-
 ## Installation
 
 DSO requires Python 3.10 or later.