doc: modify configuration section for open-tyndp specific config hierarchy and move section to getting started

Author: daniel-rdt

doc/configuration.md

@@ -7,39 +7,73 @@
 
 # Configuration
 
-PyPSA-Eur has several configuration options which are documented in this section.
+Open-TYNDP is configured through layered YAML files. It inherits the complete PyPSA-Eur
+configuration surface and adds a TYNDP-specific layer on top, so the options documented in
+this section span both the general PyPSA-Eur settings and the Open-TYNDP additions. Both
+Open-TYNDP workflows, [Scenario Building (SB)](sb.md) and
+[Cost-Benefit Analysis (CBA)](cba.md), are driven by the same set of files.
 
 <a id="defaultconfig"></a>
 
 
 ## Configuration Files
 
-As for PyPSA-Eur, any Open-TYNDP configuration can be set in a `.yaml` file. The default configurations
-`config/config.default.yaml`, `config/plotting.default.yaml` and `config/benchmarking.default.yaml`
-are maintained in the repository and cover all the options that are used/ can be set.
-
-To pass your own configuration, you can create a new file, e.g. `my_config.yaml`,
-and specify the options you want to change. They will override the default settings and
-options which are not set, will be inherited from the defaults above.
-
-Another way is to use the `config/config.yaml` file, which does not exist in the
-repository and is also not tracked by git. But snakemake will always use this file if
-it exists. This way you can run snakemake with a custom config without having to
-specify the config file each time.
-
-Configuration order of precedence is as follows:
-1. Command line options specified with `--config` (optional)
-2. Custom configuration file specified with `--configfile` (optional)
-3. The `config/config.yaml` file (optional)
-4. The default configuration files `config/config.default.yaml` and `config/plotting.default.yaml`
-
-To use your custom configuration file, you need to pass it to the `snakemake` command
-using the `--configfile` option:
+The configuration of an Open-TYNDP run is set from several files. The list below follows the
+hierarchy in which they are applied, from the base defaults up to the most specific overrides,
+with each layer overriding the ones listed before it:
+
+- **`config/config.default.yaml`** — the base defaults, auto-generated from the configuration
+  schema and inherited from PyPSA-Eur. Together with `config/plotting.default.yaml` and
+  `config/benchmarking.default.yaml`, it covers every option that can be set and provides a
+  value for each. These files are maintained in the repository and should not be edited
+  directly.
+- **`config/data.tyndp.yaml`** — an optional data-source layer, loaded on top of the defaults
+  when [`data_config: tyndp`](#data_config_cf) is set. It switches the supported datasets to the
+  Open-TYNDP archive mirror on Google Cloud Storage (see [Data Sources](sb.md#tyndp_archive)).
+- **`config/config.yaml`** — your own local overrides. This file is not part of the repository
+  and is not tracked by git, but Snakemake always picks it up if it exists, which makes it a
+  convenient place to keep machine-specific settings without touching the tracked files. You
+  can use `config/config.private.template.yaml` as a starting point.
+- **`config/config.tyndp.yaml`** — the Open-TYNDP run-level configuration. This is the file
+  passed to Snakemake by the `pixi run tyndp-sb` and `pixi run tyndp-cba` entry points via
+  `--configfile`, so it overrides all of the layers above. It activates the TYNDP-specific
+  rules (through [`tyndp_scenario`](#tyndp_scenario_cf)) and sets the model-wide choices shared
+  across scenarios, such as the modelled countries, snapshots, foresight mode, and planning
+  horizons.
+- **`config/scenarios.tyndp.yaml`** — the per-scenario overrides, applied on top of the
+  run-level configuration. `config.tyndp.yaml` points to this file through `run.scenarios.file`
+  and switches it on with `run.scenarios.enable: true`. Each named scenario (e.g. `NT`, `DE`,
+  `GA`, or a climate-year collection) supplies only the settings that differ from the run-level
+  configuration and is selected through the `{run}` wildcard. See
+  [Scenario Building](sb.md#configuration) and
+  [Cost-Benefit Analysis](cba.md#running-single-vs-multiple-climate-years) for how each
+  workflow uses these scenarios.
+
+Any option you set in a higher layer overrides the value from the layers below it, while
+options you leave unset are inherited from the defaults. To try out a change you therefore only
+need to specify the handful of options that differ — everything else falls back to
+`config.tyndp.yaml` and the defaults.
+
+Beyond these files, you are free to add configuration files of your own, e.g. `my_config.yaml`,
+and pass them explicitly to Snakemake:
 
 ```console
 $ snakemake -call --configfile my_config.yaml
 ```
 
+Taking all of this together, the order of precedence (highest first) is as follows:
+
+1. Command-line options passed with `--config` (optional)
+2. Configuration files passed with `--configfile`, such as `config/config.tyndp.yaml` (optional)
+3. The `config/config.yaml` file (optional)
+4. The default configuration files `config/config.default.yaml`, `config/plotting.default.yaml`
+   and `config/benchmarking.default.yaml`
+
+On top of this, the per-scenario overrides from `config/scenarios.tyndp.yaml` are merged in for
+the scenario selected by the `{run}` wildcard. Note that because `config.tyndp.yaml` is passed
+with `--configfile`, it takes precedence over `config/config.yaml`; to override a value that
+`config.tyndp.yaml` already sets, pass it on the command line with `--config` or edit
+`config.tyndp.yaml` directly or via the scenario file `scenarios.tyndp.yaml`.
 
 !!! warning
     In a previous version of PyPSA-Eur (`<=2025.04.0`), a full copy of the created config

mkdocs.yml

@@ -38,6 +38,7 @@ nav:
   - Getting Started:
     - Introduction: introduction.md
     - Installation: installation.md
+    - Configuration: configuration.md
     - FAQ and Troubleshooting: faq_troubleshooting.md
   - References:
     - Release Notes: release_notes.md
@@ -67,7 +68,6 @@ nav:
     - Validation: validation.md
   - Configuration:
     - Wildcards: wildcards.md
-    - Configuration: configuration.md
   - References:
     - FAQ: faq.md